Documentation/arm/XScale/IOP3XX/aau.txt

   1 Support functions for the Intel 80310 AAU
   2 ===========================================
   3
   4 Dave Jiang <dave.jiang@intel.com>
   5 Last updated: 09/18/2001
   6
   7 The Intel 80312 companion chip in the 80310 chipset contains an AAU. The
   8 AAU is capable of processing up to 8 data block sources and perform XOR
   9 operations on them. This unit is typically used to accelerated XOR
  10 operations utilized by RAID storage device drivers such as RAID 5. This
  11 API is designed to provide a set of functions to take adventage of the
  12 AAU. The AAU can also be used to transfer data blocks and used as a memory
  13 copier. The AAU transfer the memory faster than the operation performed by
  14 using CPU copy therefore it is recommended to use the AAU for memory copy.
  15
  16 ------------------
  17 int aau_request(u32 *aau_context, const char *device_id);
  18 This function allows the user the acquire the control of the the AAU. The
  19 function will return a context of AAU to the user and allocate
  20 an interrupt for the AAU. The user must pass the context as a parameter to
  21 various AAU API calls.
  22
  23 int aau_queue_buffer(u32 aau_context, aau_head_t *listhead);
  24 This function starts the AAU operation. The user must create a SGL
  25 header with a SGL attached. The format is presented below. The SGL is
  26 built from kernel memory.
  27
  28 /* hardware descriptor */
  29 typedef struct _aau_desc
  30 {
  31     u32 NDA;                    /* next descriptor address [READONLY] */
  32     u32 SAR[AAU_SAR_GROUP];     /* src addrs */
  33     u32 DAR;                    /* destination addr */
  34     u32 BC;                     /* byte count */
  35     u32 DC;                     /* descriptor control */
  36     u32 SARE[AAU_SAR_GROUP];    /* extended src addrs */
  37 } aau_desc_t;
  38
  39 /* user SGL format */
  40 typedef struct _aau_sgl
  41 {
  42     aau_desc_t          aau_desc;  /* AAU HW Desc */
  43     u32                 status;    /* status of SGL [READONLY] */
  44     struct _aau_sgl     *next;     /* pointer to next SG [READONLY] */
  45     void                *dest;     /* destination addr */
  46     void                *src[AAU_SAR_GROUP];        /* source addr[4] */
  47     void                *ext_src[AAU_SAR_GROUP];    /* ext src addr[4] */
  48     u32                 total_src; /* total number of source */
  49 } aau_sgl_t;
  50
  51 /* header for user SGL */
  52 typedef struct _aau_head
  53 {
  54     u32         total;      /* total descriptors allocated */
  55     u32         status;     /* SGL status */
  56     aau_sgl_t   *list;      /* ptr to head of list */
  57     aau_callback_t  callback;  /* callback func ptr */
  58 } aau_head_t;
  59
  60
  61 The function will call aau_start() and start the AAU after it queues
  62 the SGL to the processing queue. When the function will either
  63 a. Sleep on the wait queue aau->wait_q if no callback has been provided, or
  64 b. Continue and then call the provided callback function when DMA interrupt
  65    has been triggered.
  66
  67 int aau_suspend(u32 aau_context);
  68 Stops/Suspends the AAU operation
  69
  70 int aau_free(u32 aau_context);
  71 Frees the ownership of AAU. Called when no longer need AAU service.
  72
  73 aau_sgl_t * aau_get_buffer(u32 aau_context, int num_buf);
  74 This function obtains an AAU SGL for the user. User must specify the number
  75 of descriptors to be allocated in the chain that is returned.
  76
  77 void aau_return_buffer(u32 aau_context, aau_sgl_t *list);
  78 This function returns all SGL back to the API after user is done.
  79
  80 int aau_memcpy(void *dest, void *src, u32 size);
  81 This function is a short cut for user to do memory copy utilizing the AAU for
  82 better large block memory copy vs using the CPU. This is similar to using
  83 typical memcpy() call.
  84
  85 * User is responsible for the source address(es) and the destination address.
  86   The source and destination should all be cached memory.
  87
  88
  89
  90 void aau_test()
  91 {
  92         u32 aau;
  93         char dev_id[] = "AAU";
  94         int size = 2;
  95         int err = 0;
  96         aau_head_t *head;
  97         aau_sgl_t *list;
  98         u32 i;
  99         u32 result = 0;
 100         void *src, *dest;
 101
 102         printk("Starting AAU test\n");
 103         if((err = aau_request(&aau, dev_id))<0)
 104         {
 105                 printk("test - AAU request failed: %d\n", err);
 106                 return;
 107         }
 108         else
 109         {
 110                 printk("test - AAU request successful\n");
 111         }
 112
 113         head = kmalloc(sizeof(aau_head_t), GFP_KERNEL);
 114         head->total = size;
 115         head->status = 0;
 116         head->callback = NULL;
 117
 118         list = aau_get_buffer(aau, size);
 119         if(!list)
 120         {
 121                 printk("Can't get buffers\n");
 122                 return;
 123         }
 124         head->list = list;
 125
 126         src = kmalloc(1024, GFP_KERNEL);
 127         dest = kmalloc(1024, GFP_KERNEL);
 128
 129         while(list)
 130         {
 131                 list->status = 0;
 132                 list->aau_desc->SAR[0] = (u32)src;
 133                 list->aau_desc->DAR = (u32)dest;
 134                 list->aau_desc->BC = 1024;
 135
 136                 /* see iop310-aau.h for more DCR commands */
 137                 list->aau_desc->DC = AAU_DCR_WRITE | AAU_DCR_BLKCTRL_1_DF;
 138                 if(!list->next)
 139                 {
 140                         list->aau_desc->DC = AAU_DCR_IE;
 141                         break;
 142                 }
 143                 list = list->next;
 144         }
 145
 146         printk("test- Queueing buffer for AAU operation\n");
 147         err = aau_queue_buffer(aau, head);
 148         if(err >= 0)
 149         {
 150                 printk("AAU Queue Buffer is done...\n");
 151         }
 152         else
 153         {
 154                 printk("AAU Queue Buffer failed...: %d\n", err);
 155         }
 156
 157
 158
 159 #if 1
 160         printk("freeing the AAU\n");
 161         aau_return_buffer(aau, head->list);
 162         aau_free(aau);
 163         kfree(src);
 164         kfree(dest);
 165         kfree((void *)head);
 166 #endif
 167 }
 168
 169 All Disclaimers apply. Use this at your own discretion. Neither Intel nor I
 170 will be responsible if anything goes wrong. =)
 171
 172
 173 TODO
 174 ____
 175 * Testing
 176 * Do zero-size AAU transfer/channel at init
 177   so all we have to do is chainining
 178