include/linux/parport.h

0001 /*
0002  * Any part of this program may be used in documents licensed under
0003  * the GNU Free Documentation License, Version 1.1 or any later version
0004  * published by the Free Software Foundation.
0005  */
0006 #ifndef _PARPORT_H_
0007 #define _PARPORT_H_
0008
0009
0010 #include <linux/jiffies.h>
0011 #include <linux/proc_fs.h>
0012 #include <linux/spinlock.h>
0013 #include <linux/wait.h>
0014 #include <linux/irqreturn.h>
0015 #include <linux/semaphore.h>
0016 #include <linux/device.h>
0017 #include <asm/ptrace.h>
0018 #include <uapi/linux/parport.h>
0019
0020 /* Define this later. */
0021 struct parport;
0022 struct pardevice;
0023
0024 struct pc_parport_state {
0025     unsigned int ctr;
0026     unsigned int ecr;
0027 };
0028
0029 struct ax_parport_state {
0030     unsigned int ctr;
0031     unsigned int ecr;
0032     unsigned int dcsr;
0033 };
0034
0035 /* used by both parport_amiga and parport_mfc3 */
0036 struct amiga_parport_state {
0037        unsigned char data;     /* ciaa.prb */
0038        unsigned char datadir;  /* ciaa.ddrb */
0039        unsigned char status;   /* ciab.pra & 7 */
0040        unsigned char statusdir;/* ciab.ddrb & 7 */
0041 };
0042
0043 struct ax88796_parport_state {
0044     unsigned char cpr;
0045 };
0046
0047 struct ip32_parport_state {
0048     unsigned int dcr;
0049     unsigned int ecr;
0050 };
0051
0052 struct parport_state {
0053     union {
0054         struct pc_parport_state pc;
0055         /* ARC has no state. */
0056         struct ax_parport_state ax;
0057         struct amiga_parport_state amiga;
0058         struct ax88796_parport_state ax88796;
0059         /* Atari has not state. */
0060         struct ip32_parport_state ip32;
0061         void *misc;
0062     } u;
0063 };
0064
0065 struct parport_operations {
0066     /* IBM PC-style virtual registers. */
0067     void (*write_data)(struct parport *, unsigned char);
0068     unsigned char (*read_data)(struct parport *);
0069
0070     void (*write_control)(struct parport *, unsigned char);
0071     unsigned char (*read_control)(struct parport *);
0072     unsigned char (*frob_control)(struct parport *, unsigned char mask,
0073                       unsigned char val);
0074
0075     unsigned char (*read_status)(struct parport *);
0076
0077     /* IRQs. */
0078     void (*enable_irq)(struct parport *);
0079     void (*disable_irq)(struct parport *);
0080
0081     /* Data direction. */
0082     void (*data_forward) (struct parport *);
0083     void (*data_reverse) (struct parport *);
0084
0085     /* For core parport code. */
0086     void (*init_state)(struct pardevice *, struct parport_state *);
0087     void (*save_state)(struct parport *, struct parport_state *);
0088     void (*restore_state)(struct parport *, struct parport_state *);
0089
0090     /* Block read/write */
0091     size_t (*epp_write_data) (struct parport *port, const void *buf,
0092                   size_t len, int flags);
0093     size_t (*epp_read_data) (struct parport *port, void *buf, size_t len,
0094                  int flags);
0095     size_t (*epp_write_addr) (struct parport *port, const void *buf,
0096                   size_t len, int flags);
0097     size_t (*epp_read_addr) (struct parport *port, void *buf, size_t len,
0098                  int flags);
0099
0100     size_t (*ecp_write_data) (struct parport *port, const void *buf,
0101                   size_t len, int flags);
0102     size_t (*ecp_read_data) (struct parport *port, void *buf, size_t len,
0103                  int flags);
0104     size_t (*ecp_write_addr) (struct parport *port, const void *buf,
0105                   size_t len, int flags);
0106
0107     size_t (*compat_write_data) (struct parport *port, const void *buf,
0108                      size_t len, int flags);
0109     size_t (*nibble_read_data) (struct parport *port, void *buf,
0110                     size_t len, int flags);
0111     size_t (*byte_read_data) (struct parport *port, void *buf,
0112                   size_t len, int flags);
0113     struct module *owner;
0114 };
0115
0116 struct parport_device_info {
0117     parport_device_class class;
0118     const char *class_name;
0119     const char *mfr;
0120     const char *model;
0121     const char *cmdset;
0122     const char *description;
0123 };
0124
0125 /* Each device can have two callback functions:
0126  *  1) a preemption function, called by the resource manager to request
0127  *     that the driver relinquish control of the port.  The driver should
0128  *     return zero if it agrees to release the port, and nonzero if it
0129  *     refuses.  Do not call parport_release() - the kernel will do this
0130  *     implicitly.
0131  *
0132  *  2) a wake-up function, called by the resource manager to tell drivers
0133  *     that the port is available to be claimed.  If a driver wants to use
0134  *     the port, it should call parport_claim() here.
0135  */
0136
0137 /* A parallel port device */
0138 struct pardevice {
0139     const char *name;
0140     struct parport *port;
0141     int daisy;
0142     int (*preempt)(void *);
0143     void (*wakeup)(void *);
0144     void *private;
0145     void (*irq_func)(void *);
0146     unsigned int flags;
0147     struct pardevice *next;
0148     struct pardevice *prev;
0149     struct device dev;
0150     bool devmodel;
0151     struct parport_state *state;     /* saved status over preemption */
0152     wait_queue_head_t wait_q;
0153     unsigned long int time;
0154     unsigned long int timeslice;
0155     volatile long int timeout;
0156     unsigned long waiting;       /* long req'd for set_bit --RR */
0157     struct pardevice *waitprev;
0158     struct pardevice *waitnext;
0159     void * sysctl_table;
0160 };
0161
0162 #define to_pardevice(n) container_of(n, struct pardevice, dev)
0163
0164 /* IEEE1284 information */
0165
0166 /* IEEE1284 phases. These are exposed to userland through ppdev IOCTL
0167  * PP[GS]ETPHASE, so do not change existing values. */
0168 enum ieee1284_phase {
0169     IEEE1284_PH_FWD_DATA,
0170     IEEE1284_PH_FWD_IDLE,
0171     IEEE1284_PH_TERMINATE,
0172     IEEE1284_PH_NEGOTIATION,
0173     IEEE1284_PH_HBUSY_DNA,
0174     IEEE1284_PH_REV_IDLE,
0175     IEEE1284_PH_HBUSY_DAVAIL,
0176     IEEE1284_PH_REV_DATA,
0177     IEEE1284_PH_ECP_SETUP,
0178     IEEE1284_PH_ECP_FWD_TO_REV,
0179     IEEE1284_PH_ECP_REV_TO_FWD,
0180     IEEE1284_PH_ECP_DIR_UNKNOWN,
0181 };
0182 struct ieee1284_info {
0183     int mode;
0184     volatile enum ieee1284_phase phase;
0185     struct semaphore irq;
0186 };
0187
0188 /* A parallel port */
0189 struct parport {
0190     unsigned long base; /* base address */
0191     unsigned long base_hi;  /* base address (hi - ECR) */
0192     unsigned int size;  /* IO extent */
0193     const char *name;
0194     unsigned int modes;
0195     int irq;        /* interrupt (or -1 for none) */
0196     int dma;
0197     int muxport;        /* which muxport (if any) this is */
0198     int portnum;        /* which physical parallel port (not mux) */
0199     struct device *dev; /* Physical device associated with IO/DMA.
0200                  * This may unfortulately be null if the
0201                  * port has a legacy driver.
0202                  */
0203     struct device bus_dev;  /* to link with the bus */
0204     struct parport *physport;
0205                 /* If this is a non-default mux
0206                    parport, i.e. we're a clone of a real
0207                    physical port, this is a pointer to that
0208                    port. The locking is only done in the
0209                    real port.  For a clone port, the
0210                    following structure members are
0211                    meaningless: devices, cad, muxsel,
0212                    waithead, waittail, flags, pdir,
0213                    dev, ieee1284, *_lock.
0214
0215                    It this is a default mux parport, or
0216                    there is no mux involved, this points to
0217                    ourself. */
0218
0219     struct pardevice *devices;
0220     struct pardevice *cad;  /* port owner */
0221     int daisy;      /* currently selected daisy addr */
0222     int muxsel;     /* currently selected mux port */
0223
0224     struct pardevice *waithead;
0225     struct pardevice *waittail;
0226
0227     struct list_head list;
0228     struct timer_list timer;
0229     unsigned int flags;
0230
0231     void *sysctl_table;
0232     struct parport_device_info probe_info[5]; /* 0-3 + non-IEEE1284.3 */
0233     struct ieee1284_info ieee1284;
0234
0235     struct parport_operations *ops;
0236     void *private_data;     /* for lowlevel driver */
0237
0238     int number;     /* port index - the `n' in `parportn' */
0239     spinlock_t pardevice_lock;
0240     spinlock_t waitlist_lock;
0241     rwlock_t cad_lock;
0242
0243     int spintime;
0244     atomic_t ref_count;
0245
0246     unsigned long devflags;
0247 #define PARPORT_DEVPROC_REGISTERED  0
0248     struct pardevice *proc_device;  /* Currently register proc device */
0249
0250     struct list_head full_list;
0251     struct parport *slaves[3];
0252 };
0253
0254 #define to_parport_dev(n) container_of(n, struct parport, bus_dev)
0255
0256 #define DEFAULT_SPIN_TIME 500 /* us */
0257
0258 struct parport_driver {
0259     const char *name;
0260     void (*attach) (struct parport *);
0261     void (*detach) (struct parport *);
0262     void (*match_port)(struct parport *);
0263     int (*probe)(struct pardevice *);
0264     struct device_driver driver;
0265     bool devmodel;
0266     struct list_head list;
0267 };
0268
0269 #define to_parport_driver(n) container_of(n, struct parport_driver, driver)
0270
0271 int parport_bus_init(void);
0272 void parport_bus_exit(void);
0273
0274 /* parport_register_port registers a new parallel port at the given
0275    address (if one does not already exist) and returns a pointer to it.
0276    This entails claiming the I/O region, IRQ and DMA.  NULL is returned
0277    if initialisation fails. */
0278 struct parport *parport_register_port(unsigned long base, int irq, int dma,
0279                       struct parport_operations *ops);
0280
0281 /* Once a registered port is ready for high-level drivers to use, the
0282    low-level driver that registered it should announce it.  This will
0283    call the high-level drivers' attach() functions (after things like
0284    determining the IEEE 1284.3 topology of the port and collecting
0285    DeviceIDs). */
0286 void parport_announce_port (struct parport *port);
0287
0288 /* Unregister a port. */
0289 extern void parport_remove_port(struct parport *port);
0290
0291 /* Register a new high-level driver. */
0292
0293 int __must_check __parport_register_driver(struct parport_driver *,
0294                        struct module *,
0295                        const char *mod_name);
0296 /*
0297  * parport_register_driver must be a macro so that KBUILD_MODNAME can
0298  * be expanded
0299  */
0300
0301 /**
0302  *  parport_register_driver - register a parallel port device driver
0303  *  @driver: structure describing the driver
0304  *
0305  *  This can be called by a parallel port device driver in order
0306  *  to receive notifications about ports being found in the
0307  *  system, as well as ports no longer available.
0308  *
0309  *  If devmodel is true then the new device model is used
0310  *  for registration.
0311  *
0312  *  The @driver structure is allocated by the caller and must not be
0313  *  deallocated until after calling parport_unregister_driver().
0314  *
0315  *  If using the non device model:
0316  *  The driver's attach() function may block.  The port that
0317  *  attach() is given will be valid for the duration of the
0318  *  callback, but if the driver wants to take a copy of the
0319  *  pointer it must call parport_get_port() to do so.  Calling
0320  *  parport_register_device() on that port will do this for you.
0321  *
0322  *  The driver's detach() function may block.  The port that
0323  *  detach() is given will be valid for the duration of the
0324  *  callback, but if the driver wants to take a copy of the
0325  *  pointer it must call parport_get_port() to do so.
0326  *
0327  *
0328  *  Returns 0 on success. The non device model will always succeeds.
0329  *  but the new device model can fail and will return the error code.
0330  **/
0331 #define parport_register_driver(driver)             \
0332     __parport_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
0333
0334 /* Unregister a high-level driver. */
0335 void parport_unregister_driver(struct parport_driver *);
0336
0337 /**
0338  * module_parport_driver() - Helper macro for registering a modular parport driver
0339  * @__parport_driver: struct parport_driver to be used
0340  *
0341  * Helper macro for parport drivers which do not do anything special in module
0342  * init and exit. This eliminates a lot of boilerplate. Each module may only
0343  * use this macro once, and calling it replaces module_init() and module_exit().
0344  */
0345 #define module_parport_driver(__parport_driver) \
0346     module_driver(__parport_driver, parport_register_driver, parport_unregister_driver)
0347
0348 /* If parport_register_driver doesn't fit your needs, perhaps
0349  * parport_find_xxx does. */
0350 extern struct parport *parport_find_number (int);
0351 extern struct parport *parport_find_base (unsigned long);
0352
0353 /* generic irq handler, if it suits your needs */
0354 extern irqreturn_t parport_irq_handler(int irq, void *dev_id);
0355
0356 /* Reference counting for ports. */
0357 extern struct parport *parport_get_port (struct parport *);
0358 extern void parport_put_port (struct parport *);
0359 void parport_del_port(struct parport *);
0360
0361 struct pardev_cb {
0362     int (*preempt)(void *);
0363     void (*wakeup)(void *);
0364     void *private;
0365     void (*irq_func)(void *);
0366     unsigned int flags;
0367 };
0368
0369 /*
0370  * parport_register_dev_model declares that a device is connected to a
0371  * port, and tells the kernel all it needs to know.
0372  */
0373 struct pardevice *
0374 parport_register_dev_model(struct parport *port, const char *name,
0375                const struct pardev_cb *par_dev_cb, int cnt);
0376
0377 /* parport_unregister unlinks a device from the chain. */
0378 extern void parport_unregister_device(struct pardevice *dev);
0379
0380 /* parport_claim tries to gain ownership of the port for a particular
0381    driver.  This may fail (return non-zero) if another driver is busy.
0382    If this driver has registered an interrupt handler, it will be
0383    enabled.  */
0384 extern int parport_claim(struct pardevice *dev);
0385
0386 /* parport_claim_or_block is the same, but sleeps if the port cannot
0387    be claimed.  Return value is 1 if it slept, 0 normally and -errno
0388    on error.  */
0389 extern int parport_claim_or_block(struct pardevice *dev);
0390
0391 /* parport_release reverses a previous parport_claim.  This can never
0392    fail, though the effects are undefined (except that they are bad)
0393    if you didn't previously own the port.  Once you have released the
0394    port you should make sure that neither your code nor the hardware
0395    on the port tries to initiate any communication without first
0396    re-claiming the port.  If you mess with the port state (enabling
0397    ECP for example) you should clean up before releasing the port. */
0398
0399 extern void parport_release(struct pardevice *dev);
0400
0401 /**
0402  * parport_yield - relinquish a parallel port temporarily
0403  * @dev: a device on the parallel port
0404  *
0405  * This function relinquishes the port if it would be helpful to other
0406  * drivers to do so.  Afterwards it tries to reclaim the port using
0407  * parport_claim(), and the return value is the same as for
0408  * parport_claim().  If it fails, the port is left unclaimed and it is
0409  * the driver's responsibility to reclaim the port.
0410  *
0411  * The parport_yield() and parport_yield_blocking() functions are for
0412  * marking points in the driver at which other drivers may claim the
0413  * port and use their devices.  Yielding the port is similar to
0414  * releasing it and reclaiming it, but is more efficient because no
0415  * action is taken if there are no other devices needing the port.  In
0416  * fact, nothing is done even if there are other devices waiting but
0417  * the current device is still within its "timeslice".  The default
0418  * timeslice is half a second, but it can be adjusted via the /proc
0419  * interface.
0420  **/
0421 static __inline__ int parport_yield(struct pardevice *dev)
0422 {
0423     unsigned long int timeslip = (jiffies - dev->time);
0424     if ((dev->port->waithead == NULL) || (timeslip < dev->timeslice))
0425         return 0;
0426     parport_release(dev);
0427     return parport_claim(dev);
0428 }
0429
0430 /**
0431  * parport_yield_blocking - relinquish a parallel port temporarily
0432  * @dev: a device on the parallel port
0433  *
0434  * This function relinquishes the port if it would be helpful to other
0435  * drivers to do so.  Afterwards it tries to reclaim the port using
0436  * parport_claim_or_block(), and the return value is the same as for
0437  * parport_claim_or_block().
0438  **/
0439 static __inline__ int parport_yield_blocking(struct pardevice *dev)
0440 {
0441     unsigned long int timeslip = (jiffies - dev->time);
0442     if ((dev->port->waithead == NULL) || (timeslip < dev->timeslice))
0443         return 0;
0444     parport_release(dev);
0445     return parport_claim_or_block(dev);
0446 }
0447
0448 /* Flags used to identify what a device does. */
0449 #define PARPORT_DEV_TRAN        0   /* WARNING !! DEPRECATED !! */
0450 #define PARPORT_DEV_LURK        (1<<0)  /* WARNING !! DEPRECATED !! */
0451 #define PARPORT_DEV_EXCL        (1<<1)  /* Need exclusive access. */
0452
0453 #define PARPORT_FLAG_EXCL       (1<<1)  /* EXCL driver registered. */
0454
0455 /* IEEE1284 functions */
0456 extern void parport_ieee1284_interrupt (void *);
0457 extern int parport_negotiate (struct parport *, int mode);
0458 extern ssize_t parport_write (struct parport *, const void *buf, size_t len);
0459 extern ssize_t parport_read (struct parport *, void *buf, size_t len);
0460
0461 #define PARPORT_INACTIVITY_O_NONBLOCK 1
0462 extern long parport_set_timeout (struct pardevice *, long inactivity);
0463
0464 extern int parport_wait_event (struct parport *, long timeout);
0465 extern int parport_wait_peripheral (struct parport *port,
0466                     unsigned char mask,
0467                     unsigned char val);
0468 extern int parport_poll_peripheral (struct parport *port,
0469                     unsigned char mask,
0470                     unsigned char val,
0471                     int usec);
0472
0473 /* For architectural drivers */
0474 extern size_t parport_ieee1284_write_compat (struct parport *,
0475                          const void *, size_t, int);
0476 extern size_t parport_ieee1284_read_nibble (struct parport *,
0477                         void *, size_t, int);
0478 extern size_t parport_ieee1284_read_byte (struct parport *,
0479                       void *, size_t, int);
0480 extern size_t parport_ieee1284_ecp_read_data (struct parport *,
0481                           void *, size_t, int);
0482 extern size_t parport_ieee1284_ecp_write_data (struct parport *,
0483                            const void *, size_t, int);
0484 extern size_t parport_ieee1284_ecp_write_addr (struct parport *,
0485                            const void *, size_t, int);
0486 extern size_t parport_ieee1284_epp_write_data (struct parport *,
0487                            const void *, size_t, int);
0488 extern size_t parport_ieee1284_epp_read_data (struct parport *,
0489                           void *, size_t, int);
0490 extern size_t parport_ieee1284_epp_write_addr (struct parport *,
0491                            const void *, size_t, int);
0492 extern size_t parport_ieee1284_epp_read_addr (struct parport *,
0493                           void *, size_t, int);
0494
0495 /* IEEE1284.3 functions */
0496 #define daisy_dev_name "Device ID probe"
0497 extern int parport_daisy_init (struct parport *port);
0498 extern void parport_daisy_fini (struct parport *port);
0499 extern struct pardevice *parport_open (int devnum, const char *name);
0500 extern void parport_close (struct pardevice *dev);
0501 extern ssize_t parport_device_id (int devnum, char *buffer, size_t len);
0502 extern void parport_daisy_deselect_all (struct parport *port);
0503 extern int parport_daisy_select (struct parport *port, int daisy, int mode);
0504
0505 /* Lowlevel drivers _can_ call this support function to handle irqs.  */
0506 static inline void parport_generic_irq(struct parport *port)
0507 {
0508     parport_ieee1284_interrupt (port);
0509     read_lock(&port->cad_lock);
0510     if (port->cad && port->cad->irq_func)
0511         port->cad->irq_func(port->cad->private);
0512     read_unlock(&port->cad_lock);
0513 }
0514
0515 /* Prototypes from parport_procfs */
0516 extern int parport_proc_register(struct parport *pp);
0517 extern int parport_proc_unregister(struct parport *pp);
0518 extern int parport_device_proc_register(struct pardevice *device);
0519 extern int parport_device_proc_unregister(struct pardevice *device);
0520
0521 /* If PC hardware is the only type supported, we can optimise a bit.  */
0522 #if !defined(CONFIG_PARPORT_NOT_PC)
0523
0524 #include <linux/parport_pc.h>
0525 #define parport_write_data(p,x)            parport_pc_write_data(p,x)
0526 #define parport_read_data(p)               parport_pc_read_data(p)
0527 #define parport_write_control(p,x)         parport_pc_write_control(p,x)
0528 #define parport_read_control(p)            parport_pc_read_control(p)
0529 #define parport_frob_control(p,m,v)        parport_pc_frob_control(p,m,v)
0530 #define parport_read_status(p)             parport_pc_read_status(p)
0531 #define parport_enable_irq(p)              parport_pc_enable_irq(p)
0532 #define parport_disable_irq(p)             parport_pc_disable_irq(p)
0533 #define parport_data_forward(p)            parport_pc_data_forward(p)
0534 #define parport_data_reverse(p)            parport_pc_data_reverse(p)
0535
0536 #else  /*  !CONFIG_PARPORT_NOT_PC  */
0537
0538 /* Generic operations vector through the dispatch table. */
0539 #define parport_write_data(p,x)            (p)->ops->write_data(p,x)
0540 #define parport_read_data(p)               (p)->ops->read_data(p)
0541 #define parport_write_control(p,x)         (p)->ops->write_control(p,x)
0542 #define parport_read_control(p)            (p)->ops->read_control(p)
0543 #define parport_frob_control(p,m,v)        (p)->ops->frob_control(p,m,v)
0544 #define parport_read_status(p)             (p)->ops->read_status(p)
0545 #define parport_enable_irq(p)              (p)->ops->enable_irq(p)
0546 #define parport_disable_irq(p)             (p)->ops->disable_irq(p)
0547 #define parport_data_forward(p)            (p)->ops->data_forward(p)
0548 #define parport_data_reverse(p)            (p)->ops->data_reverse(p)
0549
0550 #endif /*  !CONFIG_PARPORT_NOT_PC  */
0551
0552 extern unsigned long parport_default_timeslice;
0553 extern int parport_default_spintime;
0554
0555 #endif /* _PARPORT_H_ */