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