gpib_types.h

  1/* SPDX-License-Identifier: GPL-2.0 */
  2
  3/***************************************************************************
  4 *    copyright		   : (C) 2002 by Frank Mori Hess
  5 ***************************************************************************/
  6
  7#ifndef _GPIB_TYPES_H
  8#define _GPIB_TYPES_H
  9
 10#ifdef __KERNEL__
 11#include <linux/gpib.h>
 12#include <linux/atomic.h>
 13#include <linux/device.h>
 14#include <linux/mutex.h>
 15#include <linux/wait.h>
 16#include <linux/sched.h>
 17#include <linux/timer.h>
 18#include <linux/interrupt.h>
 19
 20struct gpib_board;
 21
 22/* config parameters that are only used by driver attach functions */
 23struct gpib_board_config {
 24	/* firmware blob */
 25	void *init_data;
 26	int init_data_length;
 27	/* IO base address to use for non-pnp cards (set by core, driver should make local copy) */
 28	u32 ibbase;
 29	void __iomem *mmibbase;
 30	/* IRQ to use for non-pnp cards (set by core, driver should make local copy) */
 31	unsigned int ibirq;
 32	/* dma channel to use for non-pnp cards (set by core, driver should make local copy) */
 33	unsigned int ibdma;
 34	/*
 35	 * pci bus of card, useful for distinguishing multiple identical pci cards
 36	 * (negative means don't care)
 37	 */
 38	int pci_bus;
 39	/*
 40	 * pci slot of card, useful for distinguishing multiple identical pci cards
 41	 * (negative means don't care)
 42	 */
 43	int pci_slot;
 44	/* sysfs device path of hardware to attach */
 45	char *device_path;
 46	/* serial number of hardware to attach */
 47	char *serial_number;
 48};
 49
 50/*
 51 * struct gpib_interface defines the interface
 52 * between the board-specific details dealt with in the drivers
 53 * and generic interface provided by gpib-common.
 54 * This really should be in a different header file.
 55 */
 56struct gpib_interface {
 57	/* name of board */
 58	char *name;
 59	/* attach() initializes board and allocates resources */
 60	int (*attach)(struct gpib_board *board, const struct gpib_board_config *config);
 61	/* detach() shuts down board and frees resources */
 62	void (*detach)(struct gpib_board *board);
 63	/*
 64	 * read() should read at most 'length' bytes from the bus into
 65	 * 'buffer'.  It should return when it fills the buffer or
 66	 * encounters an END (EOI and or EOS if appropriate).  It should set 'end'
 67	 * to be nonzero if the read was terminated by an END, otherwise 'end'
 68	 * should be zero.
 69	 * Ultimately, this will be changed into or replaced by an asynchronous
 70	 * read.  Zero return value for success, negative
 71	 * return indicates error.
 72	 * nbytes returns number of bytes read
 73	 */
 74	int (*read)(struct gpib_board *board, u8 *buffer, size_t length, int *end,
 75		    size_t *bytes_read);
 76	/*
 77	 * write() should write 'length' bytes from buffer to the bus.
 78	 * If the boolean value send_eoi is nonzero, then EOI should
 79	 * be sent along with the last byte.  Returns number of bytes
 80	 * written or negative value on error.
 81	 */
 82	int (*write)(struct gpib_board *board, u8 *buffer, size_t length, int send_eoi,
 83		     size_t *bytes_written);
 84	/*
 85	 * command() writes the command bytes in 'buffer' to the bus
 86	 * Returns zero on success or negative value on error.
 87	 */
 88	int (*command)(struct gpib_board *board, u8 *buffer, size_t length,
 89		       size_t *bytes_written);
 90	/*
 91	 * Take control (assert ATN).  If 'asyncronous' is nonzero, take
 92	 * control asyncronously (assert ATN immediately without waiting
 93	 * for other processes to complete first).  Should not return
 94	 * until board becomes controller in charge.  Returns zero no success,
 95	 * nonzero on error.
 96	 */
 97	int (*take_control)(struct gpib_board *board, int asyncronous);
 98	/*
 99	 * De-assert ATN.  Returns zero on success, nonzer on error.
100	 */
101	int (*go_to_standby)(struct gpib_board *board);
102	/* request/release control of the IFC and REN lines (system controller) */
103	int (*request_system_control)(struct gpib_board *board, int request_control);
104	/*
105	 * Asserts or de-asserts 'interface clear' (IFC) depending on
106	 * boolean value of 'assert'
107	 */
108	void (*interface_clear)(struct gpib_board *board, int assert);
109	/*
110	 * Sends remote enable command if 'enable' is nonzero, disables remote mode
111	 * if 'enable' is zero
112	 */
113	void (*remote_enable)(struct gpib_board *board, int enable);
114	/*
115	 * enable END for reads, when byte 'eos' is received.  If
116	 * 'compare_8_bits' is nonzero, then all 8 bits are compared
117	 * with the eos bytes.	Otherwise only the 7 least significant
118	 * bits are compared.
119	 */
120	int (*enable_eos)(struct gpib_board *board, u8 eos, int compare_8_bits);
121	/* disable END on eos byte (END on EOI only)*/
122	void (*disable_eos)(struct gpib_board *board);
123	/* configure parallel poll */
124	void (*parallel_poll_configure)(struct gpib_board *board, u8 configuration);
125	/* conduct parallel poll */
126	int (*parallel_poll)(struct gpib_board *board, u8 *result);
127	/* set/clear ist (individual status bit) */
128	void (*parallel_poll_response)(struct gpib_board *board, int ist);
129	/* select local parallel poll configuration mode PP2 versus remote PP1 */
130	void (*local_parallel_poll_mode)(struct gpib_board *board, int local);
131	/*
132	 * Returns current status of the bus lines.  Should be set to
133	 * NULL if your board does not have the ability to query the
134	 * state of the bus lines.
135	 */
136	int (*line_status)(const struct gpib_board *board);
137	/*
138	 * updates and returns the board's current status.
139	 * The meaning of the bits are specified in gpib_user.h
140	 * in the IBSTA section.  The driver does not need to
141	 * worry about setting the CMPL, END, TIMO, or ERR bits.
142	 */
143	unsigned int (*update_status)(struct gpib_board *board, unsigned int clear_mask);
144	/*
145	 * Sets primary address 0-30 for gpib interface card.
146	 */
147	int (*primary_address)(struct gpib_board *board, unsigned int address);
148	/*
149	 * Sets and enables, or disables secondary address 0-30
150	 * for gpib interface card.
151	 */
152	int (*secondary_address)(struct gpib_board *board, unsigned int address,
153				 int enable);
154	/*
155	 * Sets the byte the board should send in response to a serial poll.
156	 * This function should also start or stop requests for service via
157	 * IEEE 488.2 reqt/reqf, based on MSS (bit 6 of the status_byte).
158	 * If the more flexible serial_poll_response2 is implemented by the
159	 * driver, then this method should be left NULL since it will not
160	 * be used.  This method can generate spurious service requests
161	 * which are allowed by IEEE 488.2, but not ideal.
162	 *
163	 * This method should implement the serial poll response method described
164	 * by IEEE 488.2 section 11.3.3.4.3 "Allowed Coupled Control of
165	 * STB, reqt, and reqf".
166	 */
167	void (*serial_poll_response)(struct gpib_board *board, u8 status_byte);
168	/*
169	 * Sets the byte the board should send in response to a serial poll.
170	 * This function should also request service via IEEE 488.2 reqt/reqf
171	 * based on MSS (bit 6 of the status_byte) and new_reason_for_service.
172	 * reqt should be set true if new_reason_for_service is true,
173	 * and reqf should be set true if MSS is false.	 This function
174	 * will never be called with MSS false and new_reason_for_service
175	 * true simultaneously, so don't worry about that case.
176	 *
177	 * This method implements the serial poll response method described
178	 * by IEEE 488.2 section 11.3.3.4.1 "Preferred Implementation".
179	 *
180	 * If this method is left NULL by the driver, then the user library
181	 * function ibrsv2 will not work.
182	 */
183	void (*serial_poll_response2)(struct gpib_board *board, u8 status_byte,
184				      int new_reason_for_service);
185	/*
186	 * returns the byte the board will send in response to a serial poll.
187	 */
188	u8 (*serial_poll_status)(struct gpib_board *board);
189	/* adjust T1 delay */
190	int (*t1_delay)(struct gpib_board *board, unsigned int nano_sec);
191	/* go to local mode */
192	void (*return_to_local)(struct gpib_board *board);
193	/* board does not support 7 bit eos comparisons */
194	unsigned no_7_bit_eos : 1;
195	/* skip check for listeners before trying to send command bytes */
196	unsigned skip_check_for_command_acceptors : 1;
197};
198
199struct gpib_event_queue {
200	struct list_head event_head;
201	spinlock_t lock; // for access to event list
202	unsigned int num_events;
203	unsigned dropped_event : 1;
204};
205
206static inline void init_event_queue(struct gpib_event_queue *queue)
207{
208	INIT_LIST_HEAD(&queue->event_head);
209	queue->num_events = 0;
210	queue->dropped_event = 0;
211	spin_lock_init(&queue->lock);
212}
213
214/* struct for supporting polling operation when irq is not available */
215struct gpib_pseudo_irq {
216	struct timer_list timer;
217	irqreturn_t (*handler)(int irq, void *arg);
218	struct gpib_board *board;
219	atomic_t active;
220};
221
222static inline void init_gpib_pseudo_irq(struct gpib_pseudo_irq *pseudo_irq)
223{
224	pseudo_irq->handler = NULL;
225	timer_setup(&pseudo_irq->timer, NULL, 0);
226	atomic_set(&pseudo_irq->active, 0);
227}
228
229/* list so we can make a linked list of drivers */
230struct gpib_interface_list {
231	struct list_head list;
232	struct gpib_interface *interface;
233	struct module *module;
234};
235
236/*
237 * One struct gpib_board is allocated for each physical board in the computer.
238 * It provides storage for variables local to each board, and interface
239 * functions for performing operations on the board
240 */
241struct gpib_board {
242	/* functions used by this board */
243	struct gpib_interface *interface;
244	/*
245	 * Pointer to module whose use count we should increment when
246	 * interface is in use
247	 */
248	struct module *provider_module;
249	/* buffer used to store read/write data for this board */
250	u8 *buffer;
251	/* length of buffer */
252	unsigned int buffer_length;
253	/*
254	 * Used to hold the board's current status (see update_status() above)
255	 */
256	unsigned long status;
257	/*
258	 * Driver should only sleep on this wait queue.	 It is special in that the
259	 * core will wake this queue and set the TIMO bit in 'status' when the
260	 * watchdog timer times out.
261	 */
262	wait_queue_head_t wait;
263	/*
264	 * Lock that only allows one process to access this board at a time.
265	 * Has to be first in any locking order, since it can be locked over
266	 * multiple ioctls.
267	 */
268	struct mutex user_mutex;
269	/*
270	 * Mutex which compensates for removal of "big kernel lock" from kernel.
271	 * Should not be held for extended waits.
272	 */
273	struct mutex big_gpib_mutex;
274	/* pid of last process to lock the board mutex */
275	pid_t locking_pid;
276	/* lock for setting locking pid */
277	spinlock_t locking_pid_spinlock;
278	/* Spin lock for dealing with races with the interrupt handler */
279	spinlock_t spinlock;
280	/* Watchdog timer to enable timeouts */
281	struct timer_list timer;
282	/* device of attached driver if any */
283	struct device *dev;
284	/* gpib_common device gpibN */
285	struct device *gpib_dev;
286	/*
287	 * 'private_data' can be used as seen fit by the driver to
288	 * store additional variables for this board
289	 */
290	void *private_data;
291	/* Number of open file descriptors using this board */
292	unsigned int use_count;
293	/* list of open devices connected to this board */
294	struct list_head device_list;
295	/* primary address */
296	unsigned int pad;
297	/* secondary address */
298	int sad;
299	/* timeout for io operations, in microseconds */
300	unsigned int usec_timeout;
301	/* board's parallel poll configuration byte */
302	u8 parallel_poll_configuration;
303	/* t1 delay we are using */
304	unsigned int t1_nano_sec;
305	/* Count that keeps track of whether board is up and running or not */
306	unsigned int online;
307	/* number of processes trying to autopoll */
308	int autospollers;
309	/* autospoll kernel thread */
310	struct task_struct *autospoll_task;
311	/* queue for recording received trigger/clear/ifc events */
312	struct gpib_event_queue event_queue;
313	/* minor number for this board's device file */
314	int minor;
315	/* struct to deal with polling mode*/
316	struct gpib_pseudo_irq pseudo_irq;
317	/* error dong autopoll */
318	atomic_t stuck_srq;
319	struct gpib_board_config config;
320	/* Flag that indicates whether board is system controller of the bus */
321	unsigned master : 1;
322	/* individual status bit */
323	unsigned ist : 1;
324	/*
325	 * one means local parallel poll mode ieee 488.1 PP2 (or no parallel poll PP0),
326	 * zero means remote parallel poll configuration mode ieee 488.1 PP1
327	 */
328	unsigned local_ppoll_mode : 1;
329};
330
331/* element of event queue */
332struct gpib_event {
333	struct list_head list;
334	short event_type;
335};
336
337/*
338 * Each board has a list of gpib_status_queue to keep track of all open devices
339 * on the bus, so we know what address to poll when we get a service request
340 */
341struct gpib_status_queue {
342	/* list_head so we can make a linked list of devices */
343	struct list_head list;
344	unsigned int pad;	/* primary gpib address */
345	int sad;	/* secondary gpib address (negative means disabled) */
346	/* stores serial poll bytes for this device */
347	struct list_head status_bytes;
348	unsigned int num_status_bytes;
349	/* number of times this address is opened */
350	unsigned int reference_count;
351	/* flags loss of status byte error due to limit on size of queue */
352	unsigned dropped_byte : 1;
353};
354
355struct gpib_status_byte {
356	struct list_head list;
357	u8 poll_byte;
358};
359
360void init_gpib_status_queue(struct gpib_status_queue *device);
361
362/* Used to store device-descriptor-specific information */
363struct gpib_descriptor {
364	unsigned int pad;	/* primary gpib address */
365	int sad;	/* secondary gpib address (negative means disabled) */
366	atomic_t io_in_progress;
367	/*
368	 * Kernel-only reference count to prevent descriptor from being
369	 * freed while IO handlers hold a pointer to it.  Incremented
370	 * before each IO operation, decremented when done.  Unlike
371	 * io_in_progress, this cannot be modified from userspace via
372	 * general_ibstatus().
373	 */
374	atomic_t descriptor_busy;
375	unsigned is_board : 1;
376	unsigned autopoll_enabled : 1;
377};
378
379struct gpib_file_private {
380	atomic_t holding_mutex;
381	struct gpib_descriptor *descriptors[GPIB_MAX_NUM_DESCRIPTORS];
382	/* locked while descriptors are being allocated/deallocated */
383	struct mutex descriptors_mutex;
384	unsigned got_module : 1;
385};
386
387#endif	/* __KERNEL__ */
388
389#endif	/* _GPIB_TYPES_H */