Merge tag 'ata-6.3-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/dlemoal/libata

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

PARIDE v1.03   (c) 1997-8  Grant Guenther <grant@torque.net>

PATA_PARPORT   (c) 2023 Ondrej Zary

1. Introduction

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

as well as most of the clone and no-name products on the market.

To support such a wide range of devices, PARIDE, the parallel port IDE

subsystem, is actually structured in three parts.   There is a base

paride module which provides a registry and some common methods for

accessing the parallel ports.  The second component is a set of

high-level drivers for each of the different types of supported devices:

To support such a wide range of devices, pata_parport is actually structured

in two parts. There is a base pata_parport module which provides an interface

to kernel libata subsystem, registry and some common methods for accessing

the parallel ports.

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

	pd	IDE disk

	pcd	ATAPI CD-ROM

	pf	ATAPI disk

	pt	ATAPI tape

	pg	ATAPI generic

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

(Currently, the pg driver is only used with CD-R drives).

The high-level drivers function according to the relevant standards.

The third component of PARIDE is a set of low-level protocol drivers

for each of the parallel port IDE adapter chips.  Thanks to the interest

and encouragement of Linux users from many parts of the world,

support is available for almost all known adapter protocols:

The second component is a set of low-level protocol drivers for each of the

parallel port IDE adapter chips.  Thanks to the interest and encouragement of

Linux users from many parts of the world, support is available for almost all

known adapter protocols:

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

        aten    ATEN EH-100                            (HK)

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

2. Using the PARIDE subsystem

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

2. Using pata_parport subsystem

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

While configuring the Linux kernel, you may choose either to build

the PARIDE drivers into your kernel, or to build them as modules.

the pata_parport drivers into your kernel, or to build them as modules.

In either case, you will need to select "Parallel port IDE device support"

as well as at least one of the high-level drivers and at least one

of the parallel port communication protocols.  If you do not know

what kind of parallel port adapter is used in your drive, you could

begin by checking the file names and any text files on your DOS

and at least one of the parallel port communication protocols.

If you do not know what kind of parallel port adapter is used in your drive,

you could begin by checking the file names and any text files on your DOS

installation floppy.  Alternatively, you can look at the markings on

the adapter chip itself.  That's usually sufficient to identify the

correct device.

You can actually select all the protocol modules, and allow the PARIDE

You can actually select all the protocol modules, and allow the pata_parport

subsystem to try them all for you.

For the "brand-name" products listed above, here are the protocol

and high-level drivers that you would use:

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

	Manufacturer		Model		Driver	Protocol

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

	MicroSolutions		CD-ROM		pcd	bpck

	MicroSolutions		PD drive	pf	bpck

	MicroSolutions		hard-drive	pd	bpck

	MicroSolutions          8000t tape      pt      bpck

	SyQuest			EZ, SparQ	pd	epat

	Imation			Superdisk	pf	epat

	Maxell                  Superdisk       pf      friq

	Avatar			Shark		pd	epat

	FreeCom			CD-ROM		pcd	frpw

	Hewlett-Packard		5GB Tape	pt	epat

	Hewlett-Packard		7200e (CD)	pcd	epat

	Hewlett-Packard		7200e (CD-R)	pg	epat

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

2.1  Configuring built-in drivers

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

We recommend that you get to know how the drivers work and how to

configure them as loadable modules, before attempting to compile a

kernel with the drivers built-in.

If you built all of your PARIDE support directly into your kernel,

and you have just a single parallel port IDE device, your kernel should

locate it automatically for you.  If you have more than one device,

you may need to give some command line options to your bootloader

(eg: LILO), how to do that is beyond the scope of this document.

The high-level drivers accept a number of command line parameters, all

of which are documented in the source files in linux/drivers/block/paride.

By default, each driver will automatically try all parallel ports it

can find, and all protocol types that have been installed, until it finds

a parallel port IDE adapter.  Once it finds one, the probe stops.  So,

if you have more than one device, you will need to tell the drivers

how to identify them.  This requires specifying the port address, the

protocol identification number and, for some devices, the drive's

chain ID.  While your system is booting, a number of messages are

displayed on the console.  Like all such messages, they can be

reviewed with the 'dmesg' command.  Among those messages will be

some lines like::

	paride: bpck registered as protocol 0

	paride: epat registered as protocol 1

The numbers will always be the same until you build a new kernel with

different protocol selections.  You should note these numbers as you

will need them to identify the devices.

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

	Manufacturer		Model		Protocol

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

	MicroSolutions		CD-ROM		bpck

	MicroSolutions		PD drive	bpck

	MicroSolutions		hard-drive	bpck

	MicroSolutions          8000t tape      bpck

	SyQuest			EZ, SparQ	epat

	Imation			Superdisk	epat

	Maxell                  Superdisk       friq

	Avatar			Shark		epat

	FreeCom			CD-ROM		frpw

	Hewlett-Packard		5GB Tape	epat

	Hewlett-Packard		7200e (CD)	epat

	Hewlett-Packard		7200e (CD-R)	epat

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

All parports and all protocol drivers are probed automatically unless probe=0

parameter is used. So just "modprobe epat" is enough for a Imation SuperDisk

drive to work.

Manual device creation::

	# echo "port protocol mode unit delay" >/sys/bus/pata_parport/new_device

where:

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

	port	 parport name (or "auto" for all parports)

	protocol protocol name (or "auto" for all protocols)

	mode	 mode number (protocol-specific) or -1 for probe

	unit	 unit number (for backpack only, see below)

	delay	 I/O delay (see troubleshooting section below)

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

If you happen to be using a MicroSolutions backpack device, you will

also need to know the unit ID number for each drive.  This is usually

the last two digits of the drive's serial number (but read MicroSolutions'

documentation about this).

As an example, let's assume that you have a MicroSolutions PD/CD drive

with unit ID number 36 connected to the parallel port at 0x378, a SyQuest

EZ-135 connected to the chained port on the PD/CD drive and also an

Imation Superdisk connected to port 0x278.  You could give the following

options on your boot command::

	pd.drive0=0x378,1 pf.drive0=0x278,1 pf.drive1=0x378,0,36

In the last option, pf.drive1 configures device /dev/pf1, the 0x378

is the parallel port base address, the 0 is the protocol registration

number and 36 is the chain ID.

Please note:  while PARIDE will work both with and without the

PARPORT parallel port sharing system that is included by the

"Parallel port support" option, PARPORT must be included and enabled

if you want to use chains of devices on the same parallel port.

2.2  Loading and configuring PARIDE as modules

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

It is much faster and simpler to get to understand the PARIDE drivers

if you use them as loadable kernel modules.

Note 1:

	using these drivers with the "kerneld" automatic module loading

	system is not recommended for beginners, and is not documented here.

Note 2:

	if you build PARPORT support as a loadable module, PARIDE must

	also be built as loadable modules, and PARPORT must be loaded before

	the PARIDE modules.

To use PARIDE, you must begin by::

	insmod paride

this loads a base module which provides a registry for the protocols,

among other tasks.

Then, load as many of the protocol modules as you think you might need.

As you load each module, it will register the protocols that it supports,

and print a log message to your kernel log file and your console. For

example::

	# insmod epat

	paride: epat registered as protocol 0

	# insmod kbic

	paride: k951 registered as protocol 1

        paride: k971 registered as protocol 2

Finally, you can load high-level drivers for each kind of device that

you have connected.  By default, each driver will autoprobe for a single

device, but you can support up to four similar devices by giving their

individual coordinates when you load the driver.

For example, if you had two no-name CD-ROM drives both using the

KingByte KBIC-951A adapter, one on port 0x378 and the other on 0x3bc

you could give the following command::

	# insmod pcd drive0=0x378,1 drive1=0x3bc,1

For most adapters, giving a port address and protocol number is sufficient,

but check the source files in linux/drivers/block/paride for more

information.  (Hopefully someone will write some man pages one day !).

As another example, here's what happens when PARPORT is installed, and

a SyQuest EZ-135 is attached to port 0x378::

	# insmod paride

	paride: version 1.0 installed

	# insmod epat

	paride: epat registered as protocol 0

	# insmod pd

	pd: pd version 1.0, major 45, cluster 64, nice 0

	pda: Sharing parport1 at 0x378

	pda: epat 1.0, Shuttle EPAT chip c3 at 0x378, mode 5 (EPP-32), delay 1

	pda: SyQuest EZ135A, 262144 blocks [128M], (512/16/32), removable media

	 pda: pda1

Note that the last line is the output from the generic partition table

scanner - in this case it reports that it has found a disk with one partition.

2.3  Using a PARIDE device

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

Once the drivers have been loaded, you can access PARIDE devices in the

same way as their traditional counterparts.  You will probably need to

create the device "special files".  Here is a simple script that you can

cut to a file and execute::

  #!/bin/bash

  #

  # mkd -- a script to create the device special files for the PARIDE subsystem

  #

  function mkdev {

    mknod $1 $2 $3 $4 ; chmod 0660 $1 ; chown root:disk $1

  }

  #

  function pd {

    D=$( printf \\$( printf "x%03x" $[ $1 + 97 ] ) )

    mkdev pd$D b 45 $[ $1 * 16 ]

    for P in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

    do mkdev pd$D$P b 45 $[ $1 * 16 + $P ]

    done

  }

  #

  cd /dev

  #

  for u in 0 1 2 3 ; do pd $u ; done

  for u in 0 1 2 3 ; do mkdev pcd$u b 46 $u ; done

  for u in 0 1 2 3 ; do mkdev pf$u  b 47 $u ; done

  for u in 0 1 2 3 ; do mkdev pt$u  c 96 $u ; done

  for u in 0 1 2 3 ; do mkdev npt$u c 96 $[ $u + 128 ] ; done

  for u in 0 1 2 3 ; do mkdev pg$u  c 97 $u ; done

  #

  # end of mkd

With the device files and drivers in place, you can access PARIDE devices

like any other Linux device.   For example, to mount a CD-ROM in pcd0, use::

	mount /dev/pcd0 /cdrom

If you have a fresh Avatar Shark cartridge, and the drive is pda, you

might do something like::

	fdisk /dev/pda		-- make a new partition table with

				   partition 1 of type 83

	mke2fs /dev/pda1	-- to build the file system

	mkdir /shark		-- make a place to mount the disk

	mount /dev/pda1 /shark

Devices like the Imation superdisk work in the same way, except that

they do not have a partition table.  For example to make a 120MB

floppy that you could share with a DOS system::

	mkdosfs /dev/pf0

	mount /dev/pf0 /mnt

2.4  The pf driver

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

The pf driver is intended for use with parallel port ATAPI disk

devices.  The most common devices in this category are PD drives

and LS-120 drives.  Traditionally, media for these devices are not

partitioned.  Consequently, the pf driver does not support partitioned

media.  This may be changed in a future version of the driver.

2.5  Using the pt driver

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

The pt driver for parallel port ATAPI tape drives is a minimal driver.

It does not yet support many of the standard tape ioctl operations.

For best performance, a block size of 32KB should be used.  You will

probably want to set the parallel port delay to 0, if you can.

2.6  Using the pg driver

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

The pg driver can be used in conjunction with the cdrecord program

to create CD-ROMs.  Please get cdrecord version 1.6.1 or later

from ftp://ftp.fokus.gmd.de/pub/unix/cdrecord/ .  To record CD-R media

your parallel port should ideally be set to EPP mode, and the "port delay"

should be set to 0.  With those settings it is possible to record at 2x

speed without any buffer underruns.  If you cannot get the driver to work

in EPP mode, try to use "bidirectional" or "PS/2" mode and 1x speeds only.

If you omit the parameters from the end, defaults will be used, e.g.:

Probe all parports with all protocols::

	# echo auto >/sys/bus/pata_parport/new_device

Probe parport0 using protocol epat and mode 4 (EPP-16)::

	# echo "parport0 epat 4" >/sys/bus/pata_parport/new_device

Probe parport0 using all protocols::

	# echo "parport0 auto" >/sys/bus/pata_parport/new_device

Probe all parports using protoocol epat::

	# echo "auto epat" >/sys/bus/pata_parport/new_device

Deleting devices::

	# echo pata_parport.0 >/sys/bus/pata_parport/delete_device

3. Troubleshooting

3.1  Use EPP mode if you can

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

The most common problems that people report with the PARIDE drivers

The most common problems that people report with the pata_parport drivers

concern the parallel port CMOS settings.  At this time, none of the

PARIDE protocol modules support ECP mode, or any ECP combination modes.

protocol modules support ECP mode, or any ECP combination modes.

If you are able to do so, please set your parallel port into EPP mode

using your CMOS setup procedure.

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

Some parallel ports cannot reliably transfer data at full speed.  To

offset the errors, the PARIDE protocol modules introduce a "port

offset the errors, the protocol modules introduce a "port

delay" between each access to the i/o ports.  Each protocol sets

a default value for this delay.  In most cases, the user can override

the default and set it to 0 - resulting in somewhat higher transfer

rates.  In some rare cases (especially with older 486 systems) the

default delays are not long enough.  if you experience corrupt data

transfers, or unexpected failures, you may wish to increase the

port delay.   The delay can be programmed using the "driveN" parameters

to each of the high-level drivers.  Please see the notes above, or

read the comments at the beginning of the driver source files in

linux/drivers/block/paride.

port delay.

3.3  Some drives need a printer reset

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

drives based on OnSpec and older Freecom adapters.  In these rare cases,

the adapter can often be reinitialised by issuing a "printer reset" on

the parallel port.  As the reset operation is potentially disruptive in

multiple device environments, the PARIDE drivers will not do it

multiple device environments, the pata_parport drivers will not do it

automatically.  You can however, force a printer reset by doing::

	insmod lp reset=1

	rmmod lp

If you have one of these marginal cases, you should probably build

your paride drivers as modules, and arrange to do the printer reset

before loading the PARIDE drivers.

3.4  Use the verbose option and dmesg if you need help

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

While a lot of testing has gone into these drivers to make them work

as smoothly as possible, problems will arise.  If you do have problems,

please check all the obvious things first:  does the drive work in

DOS with the manufacturer's drivers ?  If that doesn't yield any useful

clues, then please make sure that only one drive is hooked to your system,

and that either (a) PARPORT is enabled or (b) no other device driver

is using your parallel port (check in /proc/ioports).  Then, load the

appropriate drivers (you can load several protocol modules if you want)

as in::

	# insmod paride

	# insmod epat

	# insmod bpck

	# insmod kbic

	...

	# insmod pd verbose=1

(using the correct driver for the type of device you have, of course).

The verbose=1 parameter will cause the drivers to log a trace of their

activity as they attempt to locate your drive.

Use 'dmesg' to capture a log of all the PARIDE messages (any messages

beginning with paride:, a protocol module's name or a driver's name) and

include that with your bug report.  You can submit a bug report in one

of two ways.  Either send it directly to the author of the PARIDE suite,

by e-mail to grant@torque.net, or join the linux-parport mailing list

and post your report there.

3.5  For more information or help

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

You can join the linux-parport mailing list by sending a mail message

to:

		linux-parport-request@torque.net

with the single word::

		subscribe

in the body of the mail message (not in the subject line).   Please be

sure that your mail program is correctly set up when you do this,  as

the list manager is a robot that will subscribe you using the reply

address in your mail headers.  REMOVE any anti-spam gimmicks you may

have in your mail headers, when sending mail to the list server.

You might also find some useful information on the linux-parport

web pages (although they are not always up to date) at

	http://web.archive.org/web/%2E/http://www.torque.net/parport/

your pata_parport drivers as modules, and arrange to do the printer reset

before loading the pata_parport drivers.

	NFS	Appropriate NFS support is enabled.

	OF	Devicetree is enabled.

	PV_OPS	A paravirtualized kernel is enabled.

	PARIDE	The ParIDE (parallel port IDE) subsystem is enabled.

	PARISC	The PA-RISC architecture is enabled.

	PCI	PCI bus support is enabled.

	PCIE	PCI Express support is enabled.

			* [no]setxfer: Indicate if transfer speed mode setting

			  should be skipped.

			* [no]fua: Disable or enable FUA (Force Unit Access)

			  support for devices supporting this feature.

			* dump_id: Dump IDENTIFY data.

			* disable: Disable this device.

	pcbit=		[HW,ISDN]

	pcd.		[PARIDE]

			See header of drivers/block/paride/pcd.c.

			See also Documentation/admin-guide/blockdev/paride.rst.

	pci=option[,option...]	[PCI] various PCI subsystem options.

				Some options herein operate on a specific device

			for debug and development, but should not be

			needed on a platform with proper driver support.

	pd.		[PARIDE]

			See Documentation/admin-guide/blockdev/paride.rst.

	pdcchassis=	[PARISC,HW] Disable/Enable PDC Chassis Status codes at

			boot time.

			Format: { 0 | 1 }

			allocator.  This parameter is primarily	for debugging

			and performance comparison.

	pf.		[PARIDE]

			See Documentation/admin-guide/blockdev/paride.rst.

	pg.		[PARIDE]

			See Documentation/admin-guide/blockdev/paride.rst.

	pirq=		[SMP,APIC] Manual mp-table setup

			See Documentation/x86/i386/IO-APIC.rst.

	pstore.backend=	Specify the name of the pstore backend to use

	pt.		[PARIDE]

			See Documentation/admin-guide/blockdev/paride.rst.

	pti=		[X86-64] Control Page Table Isolation of user and

			kernel address spaces.  Disabling this feature

			removes hardening, but improves performance of

F:	arch/*/kernel/paravirt*

F:	include/linux/hypervisor.h

PARIDE DRIVERS FOR PARALLEL PORT IDE DEVICES

M:	Tim Waugh <tim@cyberelk.net>

L:	linux-parport@lists.infradead.org (subscribers-only)

S:	Maintained

F:	Documentation/admin-guide/blockdev/paride.rst

F:	drivers/block/paride/

PARISC ARCHITECTURE

M:	"James E.J. Bottomley" <James.Bottomley@HansenPartnership.com>

M:	Helge Deller <deller@gmx.de>

	 * Filter flush bio's early so that bio based drivers without flush

	 * support don't have to worry about them.

	 */

	if (op_is_flush(bio->bi_opf) &&

	    !test_bit(QUEUE_FLAG_WC, &q->queue_flags)) {

	if (op_is_flush(bio->bi_opf)) {

		if (WARN_ON_ONCE(bio_op(bio) != REQ_OP_WRITE &&

				 bio_op(bio) != REQ_OP_ZONE_APPEND))

			goto end_io;

		if (!test_bit(QUEUE_FLAG_WC, &q->queue_flags)) {

			bio->bi_opf &= ~(REQ_PREFLUSH | REQ_FUA);

			if (!bio_sectors(bio)) {

				status = BLK_STS_OK;

				goto end_io;

			}

		}

	}

	if (!test_bit(QUEUE_FLAG_POLL, &q->queue_flags))

		bio_clear_polled(bio);