[PARPORT] parport documentation


Tim Waugh (tim@cyberelk.demon.co.uk)
Tue, 29 Sep 1998 18:52:14 +0100 (BST)


Is this any use to anyone?

Tim.
*/

PARPORT interface documentation
-------------------------------

parport_enumerate - retrieve a list of parallel ports
-----------------

SYNOPSIS

#include <linux/parport.h>

struct parport *parport_enumerate (void);

DESCRIPTION

Retrieve the first of a list of valid parallel ports for this machine.
Successive parallel ports can be found using the 'struct parport
*next' element of the 'struct parport *' that is returned. If 'next'
is NULL, there are no more parallel ports in the list. The number of
ports in the list will not exceed PARPORT_MAX.

The returned structure contains the following fields (and others not
pictured):

struct parport
{
        struct parport *next; /* next parport in list */
        struct parport *prev; /* previous parport in list */
        const char *name; /* port's name */
        unsigned int modes; /* bitfield of supported modes */
        struct parport_device_info probe_info; /* IEEE1284 info */
        void *private_data; /* driver-specific data */
        int number; /* parport index */
        ...
};

Supported modes (these may be bitwise-ored together in 'modes') are:

  PARPORT_MODE_PCSPP
  PARPORT_MODE_PCPS2
  PARPORT_MODE_PCEPP
  PARPORT_MODE_PCECP
  PARPORT_MODE_PCECPEPP
  PARPORT_MODE_PCECR (this just means an ECR is present)
  PARPORT_MODE_PCECPPS2

RETURN VALUE

A 'struct parport *' describing a valid parallel port for the machine,
or NULL if there are none.

ERRORS

This function can return NULL to indicate that there are no parallel
ports to use.

EXAMPLE

int detect_device (void)
{
        struct parport *port;

        for (port = parport_enumerate ();
             port != NULL;
             port = port->next) {
                if (!(port->modes & PARPORT_MODE_PCECP))
                        /* Need ECP mode for this device. */
                        continue;

                /* Try to detect a device on the port... */
        }

        /* ... */
}


parport_register_device - register to use a port
-----------------------

SYNOPSIS

#include <linux/parport.h>

typedef int (*preempt_func) (void *handle);
typedef void (*wakeup_func) (void *handle);
typedef int (*irq_func) (int irq, void *handle, struct pt_regs *);

struct pardevice *parport_register_device(struct parport *port,
                                          const char *name,
                                          preempt_func preempt,
                                          wakeup_func wakeup,
                                          irq_func irq,
                                          int flags,
                                          void *handle);

DESCRIPTION

Use this function to register your device driver on a parallel port
('port'). Once you have done that, you will be able to use
parport_claim and parport_release in order to use the port.

This function will register three callbacks into your driver:
'preempt', 'wakeup' and 'irq'. Each of these may be NULL in order to
indicate that you do not want a callback.

When the 'preempt' function is called, it is because another driver
wishes to use the parallel port. The 'preempt' function should return
non-zero if the parallel port cannot be released yet -- if zero is
returned, the port is lost to another driver and the port must be
re-claimed before use.

The 'wakeup' function is called once another driver has released the
port and no other driver has yet claimed it. You can claim the
parallel port from within the 'wakeup' function (in which case the
claim is guaranteed to succeed), or choose not to if you don't need it
now.

If an interrupt occurs on the parallel port your driver has claimed,
the 'irq' function will be called.

The 'handle' is a pointer to driver-specific data, and is passed to
the callback functions.

'flags' may be a bitwise combination of the following flags:

        Flag Meaning
  PARPORT_DEV_EXCL The device cannot share the parallel port at all.
                    Use this sparingly.

The typedefs are not actually defined -- they are only shown in order
to make the function prototype more readable.

RETURN VALUE

A 'struct pardevice *': a handle to the registered parallel port
device that can be used for parport_claim, parport_release, etc.

ERRORS

A return value of NULL indicates that there was a problem registering
a device on that port.


parport_unregister_device - finish using a port
-------------------------

SYNPOPSIS

#include <linux/parport.h>

void parport_unregister_device (struct pardevice *dev);

DESCRIPTION

This function is the opposite of parport_register_device. After using
parport_unregister_device, 'dev' is no longer a valid device handle.

RETURN VALUE

None.


parport_claim, parport_claim_or_block - claim the parallel port for a device
-------------------------------------

SYNOPSIS

#include <linux/parport.h>

int parport_claim (struct pardevice *dev);
int parport_claim_or_block (struct pardevice *dev);

DESCRIPTION

These functions attempt to gain control of the parallel port on which
'dev' is registered. 'parport_claim' does not block, but
'parport_claim_or_block' may do.

You should not try to claim a port that you have already claimed.

RETURN VALUE

A return value of zero indicates that the port was successfully
claimed, and the caller now has possession of the parallel port.

If 'parport_claim_or_block' blocks before returning successfully, the
return value is 1.

ERRORS

  -EAGAIN The port is unavailable at the moment, but another attempt
           to claim it may succeed.

SEE ALSO

parport_release


parport_release - release the parallel port
---------------

SYNOPSIS

#include <linux/parport.h>

void parport_release (struct pardevice *dev);

DESCRIPTION

Once a parallel port has been claimed, it can be released using
'parport_release'. It cannot fail, but do not release a parallel port
that you do not have possession of.

RETURN VALUE

None.

SEE ALSO

parport_claim, parport_claim_or_block, parport_yield


parport_yield, parport_yield_blocking - temporarily release a parallel port
-------------------------------------

SYNOPSIS

#include <linux/parport.h>

int parport_yield (struct pardevice *dev)
int parport_yield_blocking (struct pardevice *dev);

DESCRIPTION

When a driver has control of a parallel port, it may allow another
driver to temporarily 'borrow' it. 'parport_yield' does not block;
'parport_yield_blocking' may do.

RETURN VALUE

A return value of zero indicates that the caller still owns the port
and the call did not block.

A return value of one from 'parport_yield_blocking' indicates that the
caller still owns the port and the call blocked.

A return value of -EAGAIN indicates that the caller no longer owns the
port, and it must be re-claimed before use.

ERRORS

  -EAGAIN Ownership of the parallel port was given away.


To document
-----------

Other functions:

int parport_ieee1284_nibble_mode_ok (struct parport *port, unsigned char);
int parport_wait_peripheral (struct parport *port, unsigned char,
                             unsigned char);

Functions in the parport_ops structure.

Addition functions for lowlevel drivers:

struct parport *parport_register_port (unsigned long base, int irq, int dma,
                                       struct parport_operations *ops);

void parport_unregister_port (struct parport *port);

void parport_generic_irq (int irq, struct parport *port, struct pt_regs *regs);

Miscellaneous:

IEEE1284 information in probe_info.

Undocumented internals: parport_in_use, parport_quiesce

-- To unsubscribe, send mail to: linux-parport-request@torque.net --
-- with the single word "unsubscribe" in the body of the message. --



This archive was generated by hypermail 2.0b3 on Wed 30 Dec 1998 - 10:18:27 EST