drivers/usb/host/dwc_common_port/changes.txt

   1
   2 dwc_read_reg32() and friends now take an additional parameter, a pointer to an
   3 IO context struct. The IO context struct should live in an os-dependent struct
   4 in your driver. As an example, the dwc_usb3 driver has an os-dependent struct
   5 named 'os_dep' embedded in the main device struct. So there these calls look
   6 like this:
   7
   8         dwc_read_reg32(&usb3_dev->os_dep.ioctx, &pcd->dev_global_regs->dcfg);
   9
  10         dwc_write_reg32(&usb3_dev->os_dep.ioctx,
  11                         &pcd->dev_global_regs->dcfg, 0);
  12
  13 Note that for the existing Linux driver ports, it is not necessary to actually
  14 define the 'ioctx' member in the os-dependent struct. Since Linux does not
  15 require an IO context, its macros for dwc_read_reg32() and friends do not
  16 use the context pointer, so it is optimized away by the compiler. But it is
  17 necessary to add the pointer parameter to all of the call sites, to be ready
  18 for any future ports (such as FreeBSD) which do require an IO context.
  19
  20
  21 Similarly, dwc_alloc(), dwc_alloc_atomic(), dwc_strdup(), and dwc_free() now
  22 take an additional parameter, a pointer to a memory context. Examples:
  23
  24         addr = dwc_alloc(&usb3_dev->os_dep.memctx, size);
  25
  26         dwc_free(&usb3_dev->os_dep.memctx, addr);
  27
  28 Again, for the Linux ports, it is not necessary to actually define the memctx
  29 member, but it is necessary to add the pointer parameter to all of the call
  30 sites.
  31
  32
  33 Same for dwc_dma_alloc() and dwc_dma_free(). Examples:
  34
  35         virt_addr = dwc_dma_alloc(&usb3_dev->os_dep.dmactx, size, &phys_addr);
  36
  37         dwc_dma_free(&usb3_dev->os_dep.dmactx, size, virt_addr, phys_addr);
  38
  39
  40 Same for dwc_mutex_alloc() and dwc_mutex_free(). Examples:
  41
  42         mutex = dwc_mutex_alloc(&usb3_dev->os_dep.mtxctx);
  43
  44         dwc_mutex_free(&usb3_dev->os_dep.mtxctx, mutex);
  45
  46
  47 Same for dwc_spinlock_alloc() and dwc_spinlock_free(). Examples:
  48
  49         lock = dwc_spinlock_alloc(&usb3_dev->osdep.splctx);
  50
  51         dwc_spinlock_free(&usb3_dev->osdep.splctx, lock);
  52
  53
  54 Same for dwc_timer_alloc(). Example:
  55
  56         timer = dwc_timer_alloc(&usb3_dev->os_dep.tmrctx, "dwc_usb3_tmr1",
  57                                 cb_func, cb_data);
  58
  59
  60 Same for dwc_waitq_alloc(). Example:
  61
  62         waitq = dwc_waitq_alloc(&usb3_dev->os_dep.wtqctx);
  63
  64
  65 Same for dwc_thread_run(). Example:
  66
  67         thread = dwc_thread_run(&usb3_dev->os_dep.thdctx, func,
  68                                 "dwc_usb3_thd1", data);
  69
  70
  71 Same for dwc_workq_alloc(). Example:
  72
  73         workq = dwc_workq_alloc(&usb3_dev->osdep.wkqctx, "dwc_usb3_wkq1");
  74
  75
  76 Same for dwc_task_alloc(). Example:
  77
  78         task = dwc_task_alloc(&usb3_dev->os_dep.tskctx, "dwc_usb3_tsk1",
  79                               cb_func, cb_data);
  80
  81
  82 In addition to the context pointer additions, a few core functions have had
  83 other changes made to their parameters:
  84
  85 The 'flags' parameter to dwc_spinlock_irqsave() and dwc_spinunlock_irqrestore()
  86 has been changed from a uint64_t to a dwc_irqflags_t.
  87
  88 dwc_thread_should_stop() now takes a 'dwc_thread_t *' parameter, because the
  89 FreeBSD equivalent of that function requires it.
  90
  91 And, in addition to the context pointer, dwc_task_alloc() also adds a
  92 'char *name' parameter, to be consistent with dwc_thread_run() and
  93 dwc_workq_alloc(), and because the FreeBSD equivalent of that function
  94 requires a unique name.
  95
  96
  97 Here is a complete list of the core functions that now take a pointer to a
  98 context as their first parameter:
  99
 100         dwc_read_reg32
 101         dwc_read_reg64
 102         dwc_write_reg32
 103         dwc_write_reg64
 104         dwc_modify_reg32
 105         dwc_modify_reg64
 106         dwc_alloc
 107         dwc_alloc_atomic
 108         dwc_strdup
 109         dwc_free
 110         dwc_dma_alloc
 111         dwc_dma_free
 112         dwc_mutex_alloc
 113         dwc_mutex_free
 114         dwc_spinlock_alloc
 115         dwc_spinlock_free
 116         dwc_timer_alloc
 117         dwc_waitq_alloc
 118         dwc_thread_run
 119         dwc_workq_alloc
 120         dwc_task_alloc     Also adds a 'char *name' as its 2nd parameter
 121
 122 And here are the core functions that have other changes to their parameters:
 123
 124         dwc_spinlock_irqsave      'flags' param is now a 'dwc_irqflags_t *'
 125         dwc_spinunlock_irqrestore 'flags' param is now a 'dwc_irqflags_t'
 126         dwc_thread_should_stop    Adds a 'dwc_thread_t *' parameter
 127
 128
 129
 130 The changes to the core functions also require some of the other library
 131 functions to change:
 132
 133         dwc_cc_if_alloc() and dwc_cc_if_free() now take a 'void *memctx'
 134         (for memory allocation) as the 1st param and a 'void *mtxctx'
 135         (for mutex allocation) as the 2nd param.
 136
 137         dwc_cc_clear(), dwc_cc_add(), dwc_cc_change(), dwc_cc_remove(),
 138         dwc_cc_data_for_save(), and dwc_cc_restore_from_data() now take a
 139         'void *memctx' as the 1st param.
 140
 141         dwc_dh_modpow(), dwc_dh_pk(), and dwc_dh_derive_keys() now take a
 142         'void *memctx' as the 1st param.
 143
 144         dwc_modpow() now takes a 'void *memctx' as the 1st param.
 145
 146         dwc_alloc_notification_manager() now takes a 'void *memctx' as the
 147         1st param and a 'void *wkqctx' (for work queue allocation) as the 2nd
 148         param, and also now returns an integer value that is non-zero if
 149         allocation of its data structures or work queue fails.
 150
 151         dwc_register_notifier() now takes a 'void *memctx' as the 1st param.
 152
 153         dwc_memory_debug_start() now takes a 'void *mem_ctx' as the first
 154         param, and also now returns an integer value that is non-zero if
 155         allocation of its data structures fails.
 156
 157
 158
 159 Other miscellaneous changes:
 160
 161 The DEBUG_MEMORY and DEBUG_REGS #define's have been renamed to
 162 DWC_DEBUG_MEMORY and DWC_DEBUG_REGS.
 163
 164 The following #define's have been added to allow selectively compiling library
 165 features:
 166
 167         DWC_CCLIB
 168         DWC_CRYPTOLIB
 169         DWC_NOTIFYLIB
 170         DWC_UTFLIB
 171
 172 A DWC_LIBMODULE #define has also been added. If this is not defined, then the
 173 module code in dwc_common_linux.c is not compiled in. This allows linking the
 174 library code directly into a driver module, instead of as a standalone module.