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 "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
20 struct gpib_board;
21
22 /* config parameters that are only used by driver attach functions */
23 struct 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 */
56 struct 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
199 struct 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
init_event_queue(struct gpib_event_queue * queue)206 static 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 */
215 struct 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
init_gpib_pseudo_irq(struct gpib_pseudo_irq * pseudo_irq)222 static 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 */
230 struct 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 */
241 struct 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 spinlock_t locking_pid_spinlock; // lock for setting locking pid
277 /* Spin lock for dealing with races with the interrupt handler */
278 spinlock_t spinlock;
279 /* Watchdog timer to enable timeouts */
280 struct timer_list timer;
281 /* device of attached driver if any */
282 struct device *dev;
283 /* gpib_common device gpibN */
284 struct device *gpib_dev;
285 /*
286 * 'private_data' can be used as seen fit by the driver to
287 * store additional variables for this board
288 */
289 void *private_data;
290 /* Number of open file descriptors using this board */
291 unsigned int use_count;
292 /* list of open devices connected to this board */
293 struct list_head device_list;
294 /* primary address */
295 unsigned int pad;
296 /* secondary address */
297 int sad;
298 /* timeout for io operations, in microseconds */
299 unsigned int usec_timeout;
300 /* board's parallel poll configuration byte */
301 u8 parallel_poll_configuration;
302 /* t1 delay we are using */
303 unsigned int t1_nano_sec;
304 /* Count that keeps track of whether board is up and running or not */
305 unsigned int online;
306 /* number of processes trying to autopoll */
307 int autospollers;
308 /* autospoll kernel thread */
309 struct task_struct *autospoll_task;
310 /* queue for recording received trigger/clear/ifc events */
311 struct gpib_event_queue event_queue;
312 /* minor number for this board's device file */
313 int minor;
314 /* struct to deal with polling mode*/
315 struct gpib_pseudo_irq pseudo_irq;
316 /* error dong autopoll */
317 atomic_t stuck_srq;
318 struct gpib_board_config config;
319 /* Flag that indicates whether board is system controller of the bus */
320 unsigned master : 1;
321 /* individual status bit */
322 unsigned ist : 1;
323 /*
324 * one means local parallel poll mode ieee 488.1 PP2 (or no parallel poll PP0),
325 * zero means remote parallel poll configuration mode ieee 488.1 PP1
326 */
327 unsigned local_ppoll_mode : 1;
328 };
329
330 /* element of event queue */
331 struct gpib_event {
332 struct list_head list;
333 short event_type;
334 };
335
336 /*
337 * Each board has a list of gpib_status_queue to keep track of all open devices
338 * on the bus, so we know what address to poll when we get a service request
339 */
340 struct gpib_status_queue {
341 /* list_head so we can make a linked list of devices */
342 struct list_head list;
343 unsigned int pad; /* primary gpib address */
344 int sad; /* secondary gpib address (negative means disabled) */
345 /* stores serial poll bytes for this device */
346 struct list_head status_bytes;
347 unsigned int num_status_bytes;
348 /* number of times this address is opened */
349 unsigned int reference_count;
350 /* flags loss of status byte error due to limit on size of queue */
351 unsigned dropped_byte : 1;
352 };
353
354 struct gpib_status_byte {
355 struct list_head list;
356 u8 poll_byte;
357 };
358
359 void init_gpib_status_queue(struct gpib_status_queue *device);
360
361 /* Used to store device-descriptor-specific information */
362 struct gpib_descriptor {
363 unsigned int pad; /* primary gpib address */
364 int sad; /* secondary gpib address (negative means disabled) */
365 atomic_t io_in_progress;
366 unsigned is_board : 1;
367 unsigned autopoll_enabled : 1;
368 };
369
370 struct gpib_file_private {
371 atomic_t holding_mutex;
372 struct gpib_descriptor *descriptors[GPIB_MAX_NUM_DESCRIPTORS];
373 /* locked while descriptors are being allocated/deallocated */
374 struct mutex descriptors_mutex;
375 unsigned got_module : 1;
376 };
377
378 #endif /* __KERNEL__ */
379
380 #endif /* _GPIB_TYPES_H */
381