[PARPORT] parport documentation

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

Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Next message: Andrea Arcangeli: "Re: [PARPORT] parport-arca-2.1.123"
Previous message: misha: "[PARPORT] Re: [ANNOUNCE] ftape-4.03-pre-1"

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.