]> asedeno.scripts.mit.edu Git - linux.git/blob - include/linux/thunderbolt.h
27b9be34d4b9d60a83d659d33fb1e22e67eaaf78
[linux.git] / include / linux / thunderbolt.h
1 /*
2  * Thunderbolt service API
3  *
4  * Copyright (C) 2014 Andreas Noever <andreas.noever@gmail.com>
5  * Copyright (C) 2017, Intel Corporation
6  * Authors: Michael Jamet <michael.jamet@intel.com>
7  *          Mika Westerberg <mika.westerberg@linux.intel.com>
8  *
9  * This program is free software; you can redistribute it and/or modify
10  * it under the terms of the GNU General Public License version 2 as
11  * published by the Free Software Foundation.
12  */
13
14 #ifndef THUNDERBOLT_H_
15 #define THUNDERBOLT_H_
16
17 #include <linux/device.h>
18 #include <linux/idr.h>
19 #include <linux/list.h>
20 #include <linux/mutex.h>
21 #include <linux/mod_devicetable.h>
22 #include <linux/pci.h>
23 #include <linux/uuid.h>
24 #include <linux/workqueue.h>
25
26 enum tb_cfg_pkg_type {
27         TB_CFG_PKG_READ = 1,
28         TB_CFG_PKG_WRITE = 2,
29         TB_CFG_PKG_ERROR = 3,
30         TB_CFG_PKG_NOTIFY_ACK = 4,
31         TB_CFG_PKG_EVENT = 5,
32         TB_CFG_PKG_XDOMAIN_REQ = 6,
33         TB_CFG_PKG_XDOMAIN_RESP = 7,
34         TB_CFG_PKG_OVERRIDE = 8,
35         TB_CFG_PKG_RESET = 9,
36         TB_CFG_PKG_ICM_EVENT = 10,
37         TB_CFG_PKG_ICM_CMD = 11,
38         TB_CFG_PKG_ICM_RESP = 12,
39         TB_CFG_PKG_PREPARE_TO_SLEEP = 13,
40 };
41
42 /**
43  * enum tb_security_level - Thunderbolt security level
44  * @TB_SECURITY_NONE: No security, legacy mode
45  * @TB_SECURITY_USER: User approval required at minimum
46  * @TB_SECURITY_SECURE: One time saved key required at minimum
47  * @TB_SECURITY_DPONLY: Only tunnel Display port (and USB)
48  */
49 enum tb_security_level {
50         TB_SECURITY_NONE,
51         TB_SECURITY_USER,
52         TB_SECURITY_SECURE,
53         TB_SECURITY_DPONLY,
54 };
55
56 /**
57  * struct tb - main thunderbolt bus structure
58  * @dev: Domain device
59  * @lock: Big lock. Must be held when accessing any struct
60  *        tb_switch / struct tb_port.
61  * @nhi: Pointer to the NHI structure
62  * @ctl: Control channel for this domain
63  * @wq: Ordered workqueue for all domain specific work
64  * @root_switch: Root switch of this domain
65  * @cm_ops: Connection manager specific operations vector
66  * @index: Linux assigned domain number
67  * @security_level: Current security level
68  * @privdata: Private connection manager specific data
69  */
70 struct tb {
71         struct device dev;
72         struct mutex lock;
73         struct tb_nhi *nhi;
74         struct tb_ctl *ctl;
75         struct workqueue_struct *wq;
76         struct tb_switch *root_switch;
77         const struct tb_cm_ops *cm_ops;
78         int index;
79         enum tb_security_level security_level;
80         unsigned long privdata[0];
81 };
82
83 extern struct bus_type tb_bus_type;
84 extern struct device_type tb_service_type;
85 extern struct device_type tb_xdomain_type;
86
87 #define TB_LINKS_PER_PHY_PORT   2
88
89 static inline unsigned int tb_phy_port_from_link(unsigned int link)
90 {
91         return (link - 1) / TB_LINKS_PER_PHY_PORT;
92 }
93
94 /**
95  * struct tb_property_dir - XDomain property directory
96  * @uuid: Directory UUID or %NULL if root directory
97  * @properties: List of properties in this directory
98  *
99  * User needs to provide serialization if needed.
100  */
101 struct tb_property_dir {
102         const uuid_t *uuid;
103         struct list_head properties;
104 };
105
106 enum tb_property_type {
107         TB_PROPERTY_TYPE_UNKNOWN = 0x00,
108         TB_PROPERTY_TYPE_DIRECTORY = 0x44,
109         TB_PROPERTY_TYPE_DATA = 0x64,
110         TB_PROPERTY_TYPE_TEXT = 0x74,
111         TB_PROPERTY_TYPE_VALUE = 0x76,
112 };
113
114 #define TB_PROPERTY_KEY_SIZE    8
115
116 /**
117  * struct tb_property - XDomain property
118  * @list: Used to link properties together in a directory
119  * @key: Key for the property (always terminated).
120  * @type: Type of the property
121  * @length: Length of the property data in dwords
122  * @value: Property value
123  *
124  * Users use @type to determine which field in @value is filled.
125  */
126 struct tb_property {
127         struct list_head list;
128         char key[TB_PROPERTY_KEY_SIZE + 1];
129         enum tb_property_type type;
130         size_t length;
131         union {
132                 struct tb_property_dir *dir;
133                 u8 *data;
134                 char *text;
135                 u32 immediate;
136         } value;
137 };
138
139 struct tb_property_dir *tb_property_parse_dir(const u32 *block,
140                                               size_t block_len);
141 ssize_t tb_property_format_dir(const struct tb_property_dir *dir, u32 *block,
142                                size_t block_len);
143 struct tb_property_dir *tb_property_create_dir(const uuid_t *uuid);
144 void tb_property_free_dir(struct tb_property_dir *dir);
145 int tb_property_add_immediate(struct tb_property_dir *parent, const char *key,
146                               u32 value);
147 int tb_property_add_data(struct tb_property_dir *parent, const char *key,
148                          const void *buf, size_t buflen);
149 int tb_property_add_text(struct tb_property_dir *parent, const char *key,
150                          const char *text);
151 int tb_property_add_dir(struct tb_property_dir *parent, const char *key,
152                         struct tb_property_dir *dir);
153 void tb_property_remove(struct tb_property *tb_property);
154 struct tb_property *tb_property_find(struct tb_property_dir *dir,
155                         const char *key, enum tb_property_type type);
156 struct tb_property *tb_property_get_next(struct tb_property_dir *dir,
157                                          struct tb_property *prev);
158
159 #define tb_property_for_each(dir, property)                     \
160         for (property = tb_property_get_next(dir, NULL);        \
161              property;                                          \
162              property = tb_property_get_next(dir, property))
163
164 int tb_register_property_dir(const char *key, struct tb_property_dir *dir);
165 void tb_unregister_property_dir(const char *key, struct tb_property_dir *dir);
166
167 /**
168  * struct tb_xdomain - Cross-domain (XDomain) connection
169  * @dev: XDomain device
170  * @tb: Pointer to the domain
171  * @remote_uuid: UUID of the remote domain (host)
172  * @local_uuid: Cached local UUID
173  * @route: Route string the other domain can be reached
174  * @vendor: Vendor ID of the remote domain
175  * @device: Device ID of the demote domain
176  * @lock: Lock to serialize access to the following fields of this structure
177  * @vendor_name: Name of the vendor (or %NULL if not known)
178  * @device_name: Name of the device (or %NULL if not known)
179  * @is_unplugged: The XDomain is unplugged
180  * @resume: The XDomain is being resumed
181  * @transmit_path: HopID which the remote end expects us to transmit
182  * @transmit_ring: Local ring (hop) where outgoing packets are pushed
183  * @receive_path: HopID which we expect the remote end to transmit
184  * @receive_ring: Local ring (hop) where incoming packets arrive
185  * @service_ids: Used to generate IDs for the services
186  * @properties: Properties exported by the remote domain
187  * @property_block_gen: Generation of @properties
188  * @properties_lock: Lock protecting @properties.
189  * @get_properties_work: Work used to get remote domain properties
190  * @properties_retries: Number of times left to read properties
191  * @properties_changed_work: Work used to notify the remote domain that
192  *                           our properties have changed
193  * @properties_changed_retries: Number of times left to send properties
194  *                              changed notification
195  * @link: Root switch link the remote domain is connected (ICM only)
196  * @depth: Depth in the chain the remote domain is connected (ICM only)
197  *
198  * This structure represents connection across two domains (hosts).
199  * Each XDomain contains zero or more services which are exposed as
200  * &struct tb_service objects.
201  *
202  * Service drivers may access this structure if they need to enumerate
203  * non-standard properties but they need hold @lock when doing so
204  * because properties can be changed asynchronously in response to
205  * changes in the remote domain.
206  */
207 struct tb_xdomain {
208         struct device dev;
209         struct tb *tb;
210         uuid_t *remote_uuid;
211         const uuid_t *local_uuid;
212         u64 route;
213         u16 vendor;
214         u16 device;
215         struct mutex lock;
216         const char *vendor_name;
217         const char *device_name;
218         bool is_unplugged;
219         bool resume;
220         u16 transmit_path;
221         u16 transmit_ring;
222         u16 receive_path;
223         u16 receive_ring;
224         struct ida service_ids;
225         struct tb_property_dir *properties;
226         u32 property_block_gen;
227         struct delayed_work get_properties_work;
228         int properties_retries;
229         struct delayed_work properties_changed_work;
230         int properties_changed_retries;
231         u8 link;
232         u8 depth;
233 };
234
235 int tb_xdomain_enable_paths(struct tb_xdomain *xd, u16 transmit_path,
236                             u16 transmit_ring, u16 receive_path,
237                             u16 receive_ring);
238 int tb_xdomain_disable_paths(struct tb_xdomain *xd);
239 struct tb_xdomain *tb_xdomain_find_by_uuid(struct tb *tb, const uuid_t *uuid);
240 struct tb_xdomain *tb_xdomain_find_by_route(struct tb *tb, u64 route);
241
242 static inline struct tb_xdomain *
243 tb_xdomain_find_by_uuid_locked(struct tb *tb, const uuid_t *uuid)
244 {
245         struct tb_xdomain *xd;
246
247         mutex_lock(&tb->lock);
248         xd = tb_xdomain_find_by_uuid(tb, uuid);
249         mutex_unlock(&tb->lock);
250
251         return xd;
252 }
253
254 static inline struct tb_xdomain *
255 tb_xdomain_find_by_route_locked(struct tb *tb, u64 route)
256 {
257         struct tb_xdomain *xd;
258
259         mutex_lock(&tb->lock);
260         xd = tb_xdomain_find_by_route(tb, route);
261         mutex_unlock(&tb->lock);
262
263         return xd;
264 }
265
266 static inline struct tb_xdomain *tb_xdomain_get(struct tb_xdomain *xd)
267 {
268         if (xd)
269                 get_device(&xd->dev);
270         return xd;
271 }
272
273 static inline void tb_xdomain_put(struct tb_xdomain *xd)
274 {
275         if (xd)
276                 put_device(&xd->dev);
277 }
278
279 static inline bool tb_is_xdomain(const struct device *dev)
280 {
281         return dev->type == &tb_xdomain_type;
282 }
283
284 static inline struct tb_xdomain *tb_to_xdomain(struct device *dev)
285 {
286         if (tb_is_xdomain(dev))
287                 return container_of(dev, struct tb_xdomain, dev);
288         return NULL;
289 }
290
291 int tb_xdomain_response(struct tb_xdomain *xd, const void *response,
292                         size_t size, enum tb_cfg_pkg_type type);
293 int tb_xdomain_request(struct tb_xdomain *xd, const void *request,
294                        size_t request_size, enum tb_cfg_pkg_type request_type,
295                        void *response, size_t response_size,
296                        enum tb_cfg_pkg_type response_type,
297                        unsigned int timeout_msec);
298
299 /**
300  * tb_protocol_handler - Protocol specific handler
301  * @uuid: XDomain messages with this UUID are dispatched to this handler
302  * @callback: Callback called with the XDomain message. Returning %1
303  *            here tells the XDomain core that the message was handled
304  *            by this handler and should not be forwared to other
305  *            handlers.
306  * @data: Data passed with the callback
307  * @list: Handlers are linked using this
308  *
309  * Thunderbolt services can hook into incoming XDomain requests by
310  * registering protocol handler. Only limitation is that the XDomain
311  * discovery protocol UUID cannot be registered since it is handled by
312  * the core XDomain code.
313  *
314  * The @callback must check that the message is really directed to the
315  * service the driver implements.
316  */
317 struct tb_protocol_handler {
318         const uuid_t *uuid;
319         int (*callback)(const void *buf, size_t size, void *data);
320         void *data;
321         struct list_head list;
322 };
323
324 int tb_register_protocol_handler(struct tb_protocol_handler *handler);
325 void tb_unregister_protocol_handler(struct tb_protocol_handler *handler);
326
327 /**
328  * struct tb_service - Thunderbolt service
329  * @dev: XDomain device
330  * @id: ID of the service (shown in sysfs)
331  * @key: Protocol key from the properties directory
332  * @prtcid: Protocol ID from the properties directory
333  * @prtcvers: Protocol version from the properties directory
334  * @prtcrevs: Protocol software revision from the properties directory
335  * @prtcstns: Protocol settings mask from the properties directory
336  *
337  * Each domain exposes set of services it supports as collection of
338  * properties. For each service there will be one corresponding
339  * &struct tb_service. Service drivers are bound to these.
340  */
341 struct tb_service {
342         struct device dev;
343         int id;
344         const char *key;
345         u32 prtcid;
346         u32 prtcvers;
347         u32 prtcrevs;
348         u32 prtcstns;
349 };
350
351 static inline struct tb_service *tb_service_get(struct tb_service *svc)
352 {
353         if (svc)
354                 get_device(&svc->dev);
355         return svc;
356 }
357
358 static inline void tb_service_put(struct tb_service *svc)
359 {
360         if (svc)
361                 put_device(&svc->dev);
362 }
363
364 static inline bool tb_is_service(const struct device *dev)
365 {
366         return dev->type == &tb_service_type;
367 }
368
369 static inline struct tb_service *tb_to_service(struct device *dev)
370 {
371         if (tb_is_service(dev))
372                 return container_of(dev, struct tb_service, dev);
373         return NULL;
374 }
375
376 /**
377  * tb_service_driver - Thunderbolt service driver
378  * @driver: Driver structure
379  * @probe: Called when the driver is probed
380  * @remove: Called when the driver is removed (optional)
381  * @shutdown: Called at shutdown time to stop the service (optional)
382  * @id_table: Table of service identifiers the driver supports
383  */
384 struct tb_service_driver {
385         struct device_driver driver;
386         int (*probe)(struct tb_service *svc, const struct tb_service_id *id);
387         void (*remove)(struct tb_service *svc);
388         void (*shutdown)(struct tb_service *svc);
389         const struct tb_service_id *id_table;
390 };
391
392 #define TB_SERVICE(key, id)                             \
393         .match_flags = TBSVC_MATCH_PROTOCOL_KEY |       \
394                        TBSVC_MATCH_PROTOCOL_ID,         \
395         .protocol_key = (key),                          \
396         .protocol_id = (id)
397
398 int tb_register_service_driver(struct tb_service_driver *drv);
399 void tb_unregister_service_driver(struct tb_service_driver *drv);
400
401 static inline void *tb_service_get_drvdata(const struct tb_service *svc)
402 {
403         return dev_get_drvdata(&svc->dev);
404 }
405
406 static inline void tb_service_set_drvdata(struct tb_service *svc, void *data)
407 {
408         dev_set_drvdata(&svc->dev, data);
409 }
410
411 static inline struct tb_xdomain *tb_service_parent(struct tb_service *svc)
412 {
413         return tb_to_xdomain(svc->dev.parent);
414 }
415
416 /**
417  * struct tb_nhi - thunderbolt native host interface
418  * @lock: Must be held during ring creation/destruction. Is acquired by
419  *        interrupt_work when dispatching interrupts to individual rings.
420  * @pdev: Pointer to the PCI device
421  * @iobase: MMIO space of the NHI
422  * @tx_rings: All Tx rings available on this host controller
423  * @rx_rings: All Rx rings available on this host controller
424  * @msix_ida: Used to allocate MSI-X vectors for rings
425  * @going_away: The host controller device is about to disappear so when
426  *              this flag is set, avoid touching the hardware anymore.
427  * @interrupt_work: Work scheduled to handle ring interrupt when no
428  *                  MSI-X is used.
429  * @hop_count: Number of rings (end point hops) supported by NHI.
430  */
431 struct tb_nhi {
432         spinlock_t lock;
433         struct pci_dev *pdev;
434         void __iomem *iobase;
435         struct tb_ring **tx_rings;
436         struct tb_ring **rx_rings;
437         struct ida msix_ida;
438         bool going_away;
439         struct work_struct interrupt_work;
440         u32 hop_count;
441 };
442
443 /**
444  * struct tb_ring - thunderbolt TX or RX ring associated with a NHI
445  * @lock: Lock serializing actions to this ring. Must be acquired after
446  *        nhi->lock.
447  * @nhi: Pointer to the native host controller interface
448  * @size: Size of the ring
449  * @hop: Hop (DMA channel) associated with this ring
450  * @head: Head of the ring (write next descriptor here)
451  * @tail: Tail of the ring (complete next descriptor here)
452  * @descriptors: Allocated descriptors for this ring
453  * @queue: Queue holding frames to be transferred over this ring
454  * @in_flight: Queue holding frames that are currently in flight
455  * @work: Interrupt work structure
456  * @is_tx: Is the ring Tx or Rx
457  * @running: Is the ring running
458  * @irq: MSI-X irq number if the ring uses MSI-X. %0 otherwise.
459  * @vector: MSI-X vector number the ring uses (only set if @irq is > 0)
460  * @flags: Ring specific flags
461  * @sof_mask: Bit mask used to detect start of frame PDF
462  * @eof_mask: Bit mask used to detect end of frame PDF
463  * @start_poll: Called when ring interrupt is triggered to start
464  *              polling. Passing %NULL keeps the ring in interrupt mode.
465  * @poll_data: Data passed to @start_poll
466  */
467 struct tb_ring {
468         spinlock_t lock;
469         struct tb_nhi *nhi;
470         int size;
471         int hop;
472         int head;
473         int tail;
474         struct ring_desc *descriptors;
475         dma_addr_t descriptors_dma;
476         struct list_head queue;
477         struct list_head in_flight;
478         struct work_struct work;
479         bool is_tx:1;
480         bool running:1;
481         int irq;
482         u8 vector;
483         unsigned int flags;
484         u16 sof_mask;
485         u16 eof_mask;
486         void (*start_poll)(void *data);
487         void *poll_data;
488 };
489
490 /* Leave ring interrupt enabled on suspend */
491 #define RING_FLAG_NO_SUSPEND    BIT(0)
492 /* Configure the ring to be in frame mode */
493 #define RING_FLAG_FRAME         BIT(1)
494 /* Enable end-to-end flow control */
495 #define RING_FLAG_E2E           BIT(2)
496
497 struct ring_frame;
498 typedef void (*ring_cb)(struct tb_ring *, struct ring_frame *, bool canceled);
499
500 /**
501  * enum ring_desc_flags - Flags for DMA ring descriptor
502  * %RING_DESC_ISOCH: Enable isonchronous DMA (Tx only)
503  * %RING_DESC_CRC_ERROR: In frame mode CRC check failed for the frame (Rx only)
504  * %RING_DESC_COMPLETED: Descriptor completed (set by NHI)
505  * %RING_DESC_POSTED: Always set this
506  * %RING_DESC_BUFFER_OVERRUN: RX buffer overrun
507  * %RING_DESC_INTERRUPT: Request an interrupt on completion
508  */
509 enum ring_desc_flags {
510         RING_DESC_ISOCH = 0x1,
511         RING_DESC_CRC_ERROR = 0x1,
512         RING_DESC_COMPLETED = 0x2,
513         RING_DESC_POSTED = 0x4,
514         RING_DESC_BUFFER_OVERRUN = 0x04,
515         RING_DESC_INTERRUPT = 0x8,
516 };
517
518 /**
519  * struct ring_frame - For use with ring_rx/ring_tx
520  * @buffer_phy: DMA mapped address of the frame
521  * @callback: Callback called when the frame is finished (optional)
522  * @list: Frame is linked to a queue using this
523  * @size: Size of the frame in bytes (%0 means %4096)
524  * @flags: Flags for the frame (see &enum ring_desc_flags)
525  * @eof: End of frame protocol defined field
526  * @sof: Start of frame protocol defined field
527  */
528 struct ring_frame {
529         dma_addr_t buffer_phy;
530         ring_cb callback;
531         struct list_head list;
532         u32 size:12;
533         u32 flags:12;
534         u32 eof:4;
535         u32 sof:4;
536 };
537
538 /* Minimum size for ring_rx */
539 #define TB_FRAME_SIZE           0x100
540
541 struct tb_ring *tb_ring_alloc_tx(struct tb_nhi *nhi, int hop, int size,
542                                  unsigned int flags);
543 struct tb_ring *tb_ring_alloc_rx(struct tb_nhi *nhi, int hop, int size,
544                                  unsigned int flags, u16 sof_mask, u16 eof_mask,
545                                  void (*start_poll)(void *), void *poll_data);
546 void tb_ring_start(struct tb_ring *ring);
547 void tb_ring_stop(struct tb_ring *ring);
548 void tb_ring_free(struct tb_ring *ring);
549
550 int __tb_ring_enqueue(struct tb_ring *ring, struct ring_frame *frame);
551
552 /**
553  * tb_ring_rx() - enqueue a frame on an RX ring
554  * @ring: Ring to enqueue the frame
555  * @frame: Frame to enqueue
556  *
557  * @frame->buffer, @frame->buffer_phy have to be set. The buffer must
558  * contain at least %TB_FRAME_SIZE bytes.
559  *
560  * @frame->callback will be invoked with @frame->size, @frame->flags,
561  * @frame->eof, @frame->sof set once the frame has been received.
562  *
563  * If ring_stop() is called after the packet has been enqueued
564  * @frame->callback will be called with canceled set to true.
565  *
566  * Return: Returns %-ESHUTDOWN if ring_stop has been called. Zero otherwise.
567  */
568 static inline int tb_ring_rx(struct tb_ring *ring, struct ring_frame *frame)
569 {
570         WARN_ON(ring->is_tx);
571         return __tb_ring_enqueue(ring, frame);
572 }
573
574 /**
575  * tb_ring_tx() - enqueue a frame on an TX ring
576  * @ring: Ring the enqueue the frame
577  * @frame: Frame to enqueue
578  *
579  * @frame->buffer, @frame->buffer_phy, @frame->size, @frame->eof and
580  * @frame->sof have to be set.
581  *
582  * @frame->callback will be invoked with once the frame has been transmitted.
583  *
584  * If ring_stop() is called after the packet has been enqueued @frame->callback
585  * will be called with canceled set to true.
586  *
587  * Return: Returns %-ESHUTDOWN if ring_stop has been called. Zero otherwise.
588  */
589 static inline int tb_ring_tx(struct tb_ring *ring, struct ring_frame *frame)
590 {
591         WARN_ON(!ring->is_tx);
592         return __tb_ring_enqueue(ring, frame);
593 }
594
595 /* Used only when the ring is in polling mode */
596 struct ring_frame *tb_ring_poll(struct tb_ring *ring);
597 void tb_ring_poll_complete(struct tb_ring *ring);
598
599 /**
600  * tb_ring_dma_device() - Return device used for DMA mapping
601  * @ring: Ring whose DMA device is retrieved
602  *
603  * Use this function when you are mapping DMA for buffers that are
604  * passed to the ring for sending/receiving.
605  */
606 static inline struct device *tb_ring_dma_device(struct tb_ring *ring)
607 {
608         return &ring->nhi->pdev->dev;
609 }
610
611 #endif /* THUNDERBOLT_H_ */