PSDK QNX API Guide
udma_ring.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) Texas Instruments Incorporated 2018
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  *
8  * Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  *
11  * Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the
14  * distribution.
15  *
16  * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
48 #ifndef UDMA_RING_H_
49 #define UDMA_RING_H_
50 
51 /* ========================================================================== */
52 /* Include Files */
53 /* ========================================================================== */
54 
55 /* None */
56 
57 #ifdef __cplusplus
58 extern "C" {
59 #endif
60 
61 /* ========================================================================== */
62 /* Macros & Typedefs */
63 /* ========================================================================== */
64 
69 #define UDMA_RING_INVALID ((uint16_t) TISCI_MSG_VALUE_RM_NULL_RING_TYPE)
74 #define UDMA_RING_ANY ((uint16_t) 0xFFFEU)
79 #define UDMA_RING_MON_INVALID (UDMA_RING_INVALID)
84 #define UDMA_RING_MON_ANY (UDMA_RING_ANY)
89 #define UDMA_RING_VIRTID_INVALID ((uint16_t) 0xFFFFU)
90 
92 #define UDMA_RING_SIZE_CHECK_SKIP (0xABDCABCDU)
93 
97 #define UDMA_RING_ORDERID_MAX (0x0FU)
98 
111 #define UDMA_RING_ES_4BYTES ((uint8_t) 0x00U)
113 #define UDMA_RING_ES_8BYTES ((uint8_t) 0x01U)
115 #define UDMA_RING_ES_16BYTES ((uint8_t) 0x02U)
117 #define UDMA_RING_ES_32BYTES ((uint8_t) 0x03U)
119 #define UDMA_RING_ES_64BYTES ((uint8_t) 0x04U)
121 #define UDMA_RING_ES_128BYTES ((uint8_t) 0x05U)
123 #define UDMA_RING_ES_256BYTES ((uint8_t) 0x06U)
124 /* @} */
125 
126 /* ========================================================================== */
127 /* Structure Declarations */
128 /* ========================================================================== */
129 
133 typedef struct
134 {
135  void *ringMem;
142  uint32_t ringMemSize;
149  uint8_t mode;
151  uint16_t virtId;
153  uint32_t elemCnt;
157  uint8_t elemSize;
160  uint8_t orderId;
163  uint8_t asel;
171  uint32_t mappedRingGrp;
180  uint32_t mappedChNum;
193 } Udma_RingPrms;
194 
198 typedef struct
199 {
200  uint8_t source;
202  uint8_t mode;
204  uint16_t ringNum;
206  uint32_t data0;
216  uint32_t data1;
227 
231 typedef struct
232 {
233  uint32_t data0;
243  uint32_t data1;
254 
255 /* ========================================================================== */
256 /* Function Declarations */
257 /* ========================================================================== */
258 
279 int32_t Udma_ringAlloc(Udma_DrvHandle drvHandle,
280  Udma_RingHandle ringHandle,
281  uint16_t ringNum,
282  const Udma_RingPrms *ringPrms);
283 
296 int32_t Udma_ringFree(Udma_RingHandle ringHandle);
297 
328 int32_t Udma_ringAttach(Udma_DrvHandle drvHandle,
329  Udma_RingHandle ringHandle,
330  uint16_t ringNum);
331 
345 int32_t Udma_ringDetach(Udma_RingHandle ringHandle);
346 
375 int32_t Udma_ringQueueRaw(Udma_RingHandle ringHandle, uint64_t phyDescMem);
376 
413 int32_t Udma_ringDequeueRaw(Udma_RingHandle ringHandle, uint64_t *phyDescMem);
414 
438 int32_t Udma_ringFlushRaw(Udma_RingHandle ringHandle, uint64_t *phyDescMem);
439 
466 void Udma_ringPrime(Udma_RingHandle ringHandle, uint64_t phyDescMem);
467 
496 void Udma_ringPrimeRead(Udma_RingHandle ringHandle, uint64_t *phyDescMem);
497 
525 void Udma_ringSetDoorBell(Udma_RingHandle ringHandle, int32_t count);
526 
537 uint16_t Udma_ringGetNum(Udma_RingHandle ringHandle);
538 
549 void *Udma_ringGetMemPtr(Udma_RingHandle ringHandle);
550 
561 uint32_t Udma_ringGetMode(Udma_RingHandle ringHandle);
562 
573 uint32_t Udma_ringGetElementCnt(Udma_RingHandle ringHandle);
574 
591 uint32_t Udma_ringGetForwardRingOcc(Udma_RingHandle ringHandle);
592 
609 uint32_t Udma_ringGetReverseRingOcc(Udma_RingHandle ringHandle);
610 
627 uint32_t Udma_ringGetWrIdx(Udma_RingHandle ringHandle);
628 
645 uint32_t Udma_ringGetRdIdx(Udma_RingHandle ringHandle);
646 
668 int32_t Udma_ringMonAlloc(Udma_DrvHandle drvHandle,
669  Udma_RingMonHandle monHandle,
670  uint16_t ringMonNum);
671 
687 int32_t Udma_ringMonFree(Udma_RingMonHandle monHandle);
688 
703 int32_t Udma_ringMonConfig(Udma_RingMonHandle monHandle,
704  const Udma_RingMonPrms *monPrms);
705 
722 int32_t Udma_ringMonGetData(Udma_RingMonHandle monHandle,
723  Udma_RingMonData *monData);
724 
738 uint16_t Udma_ringMonGetNum(Udma_RingMonHandle monHandle);
739 
740 /*
741  * Structure Init functions
742  */
750 int32_t UdmaRingPrms_init(Udma_RingPrms *ringPrms);
751 
760 
761 
762 /* Proxy APIs. Moving this to be an extenal API since clients would use it
763  for proxy specific queueing */
764 int32_t Udma_ringProxyQueueRaw(Udma_RingHandle ringHandle,
765  Udma_DrvHandle drvHandle,
766  uint64_t phyDescMem);
767 int32_t Udma_ringProxyDequeueRaw(Udma_RingHandle ringHandle,
768  Udma_DrvHandle drvHandle,
769  uint64_t *phyDescMem);
770 
771 /* ========================================================================== */
772 /* Static Function Definitions */
773 /* ========================================================================== */
774 
775 /* None */
776 
777 /* ========================================================================== */
778 /* Internal/Private Structure Declarations */
779 /* ========================================================================== */
780 
788 {
789  Udma_DrvHandle drvHandle;
792  uint16_t ringNum;
795 #if (UDMA_SOC_CFG_RA_NORMAL_PRESENT == 1)
796  CSL_RingAccRingCfg cfg;
799  /* Below register overlay pointers provided for debug purpose to
800  * readily view the registers */
801  volatile CSL_ringacc_cfgRegs_RING *pCfgRegs;
803  volatile CSL_ringacc_rtRegs_RINGRT *pRtRegs;
805 #endif
806 #if (UDMA_SOC_CFG_RA_LCDMA_PRESENT == 1)
807  CSL_LcdmaRingaccRingCfg lcdmaCfg;
810  /* Below register overlay pointers provided for debug purpose to
811  * readily view the registers */
812  volatile CSL_lcdma_ringacc_ring_cfgRegs_RING *pLcdmaCfgRegs;
814  volatile CSL_lcdma_ringacc_ringrtRegs_ring *pLcdmaRtRegs;
816 #endif
817 
818 #if (UDMA_SOC_CFG_PROXY_PRESENT == 1)
819  /* Proxy address for the ring. Calculated at alloc time to reduce cycles at
820  * runtime */
821  uintptr_t proxyAddr;
823 #ifdef QNX_OS
824  uint16_t proxyNum;
826 #endif
827 #endif
828 
829  uint32_t ringInitDone;
832  uint32_t mappedRingGrp;
843  uint32_t mappedChNum;
851 };
852 
860 {
861  Udma_DrvHandle drvHandle;
864  uint16_t ringMonNum;
867 #if (UDMA_SOC_CFG_RING_MON_PRESENT == 1)
868  /* Below register overlay pointers provided for debug purpose to
869  * readily view the registers */
870  volatile CSL_ringacc_monitorRegs_mon *pMonRegs;
872 #endif
873 
874  uint32_t ringMonInitDone;
876 };
877 
878 #ifdef __cplusplus
879 }
880 #endif
881 
882 #endif /* #ifndef UDMA_RING_H_ */
883 
884 /* @} */
uint8_t mode
Definition: udma_ring.h:202
int32_t Udma_ringMonFree(Udma_RingMonHandle monHandle)
UDMA free ring monitor.
int32_t UdmaRingPrms_init(Udma_RingPrms *ringPrms)
Udma_RingPrms structure init function.
uint32_t Udma_ringGetRdIdx(Udma_RingHandle ringHandle)
Returns the ring read index value.
uint8_t source
Definition: udma_ring.h:200
uint32_t data1
Definition: udma_ring.h:243
uint16_t ringNum
Definition: udma_ring.h:204
uint8_t orderId
Definition: udma_ring.h:160
uint32_t data1
Definition: udma_ring.h:216
uint8_t mode
Definition: udma_ring.h:149
int32_t UdmaRingMonPrms_init(Udma_RingMonPrms *monPrms)
Udma_RingMonPrms structure init function.
int32_t Udma_ringDetach(Udma_RingHandle ringHandle)
UDMA detach ring API.
uint32_t Udma_ringGetForwardRingOcc(Udma_RingHandle ringHandle)
Returns the forward ring occupancy.
void * ringMem
Definition: udma_ring.h:135
int32_t Udma_ringMonGetData(Udma_RingMonHandle monHandle, Udma_RingMonData *monData)
UDMA ring monitor get data API.
uint32_t mappedRingGrp
Definition: udma_ring.h:832
int32_t Udma_ringFree(Udma_RingHandle ringHandle)
UDMA free ring.
uint32_t data0
Definition: udma_ring.h:233
void * Udma_ringGetMemPtr(Udma_RingHandle ringHandle)
Returns the ring memory pointer which is passed during ring alloc.
uint16_t ringMonNum
Definition: udma_ring.h:864
int32_t Udma_ringMonConfig(Udma_RingMonHandle monHandle, const Udma_RingMonPrms *monPrms)
UDMA ring monitor configure API.
uint8_t asel
Definition: udma_ring.h:163
uint32_t Udma_ringGetMode(Udma_RingHandle ringHandle)
Returns the ring mode which is configured during ring alloc.
uint32_t data0
Definition: udma_ring.h:206
int32_t Udma_ringAlloc(Udma_DrvHandle drvHandle, Udma_RingHandle ringHandle, uint16_t ringNum, const Udma_RingPrms *ringPrms)
UDMA ring allocation and configuration API.
int32_t Udma_ringFlushRaw(Udma_RingHandle ringHandle, uint64_t *phyDescMem)
UDMA dequeue descriptor from a ring when UDMA channel is disabled - raw version (Takes all physical p...
uint32_t mappedRingGrp
Definition: udma_ring.h:171
uint32_t ringMonInitDone
Definition: udma_ring.h:874
void Udma_ringPrime(Udma_RingHandle ringHandle, uint64_t phyDescMem)
UDMA prime descriptor to a exposed/"RING" mode ring - raw version (Takes all physical pointers)....
Udma_DrvHandle drvHandle
Definition: udma_ring.h:789
uint16_t Udma_ringMonGetNum(Udma_RingMonHandle monHandle)
Returns the ring monitor number.
uint8_t elemSize
Definition: udma_ring.h:157
void Udma_ringSetDoorBell(Udma_RingHandle ringHandle, int32_t count)
UDMA ring API to set the doorbell in exposed/"RING" mode ring. This will commit the previously primed...
int32_t Udma_ringProxyDequeueRaw(Udma_RingHandle ringHandle, Udma_DrvHandle drvHandle, uint64_t *phyDescMem)
uint16_t ringNum
Definition: udma_ring.h:792
uint32_t Udma_ringGetWrIdx(Udma_RingHandle ringHandle)
Returns the ring write index value.
int32_t Udma_ringDequeueRaw(Udma_RingHandle ringHandle, uint64_t *phyDescMem)
UDMA dequeue descriptor from a ring - raw version (Takes all physical pointers).
int32_t Udma_ringMonAlloc(Udma_DrvHandle drvHandle, Udma_RingMonHandle monHandle, uint16_t ringMonNum)
UDMA ring monitor allocation API.
uint32_t ringInitDone
Definition: udma_ring.h:829
uint32_t Udma_ringGetReverseRingOcc(Udma_RingHandle ringHandle)
Returns the reverse ring occupancy.
uint32_t elemCnt
Definition: udma_ring.h:153
int32_t Udma_ringQueueRaw(Udma_RingHandle ringHandle, uint64_t phyDescMem)
UDMA queue descriptor to a ring - raw version (Takes all physical pointers)
uint32_t Udma_ringGetElementCnt(Udma_RingHandle ringHandle)
Returns the ring element count which is passed during ring alloc.
uint32_t mappedChNum
Definition: udma_ring.h:180
int32_t Udma_ringAttach(Udma_DrvHandle drvHandle, Udma_RingHandle ringHandle, uint16_t ringNum)
UDMA ring attach API. This API is used to attach to an already allocated and configured ring....
uint32_t ringMemSize
Definition: udma_ring.h:142
uint32_t mappedChNum
Definition: udma_ring.h:843
Udma_DrvHandle drvHandle
Definition: udma_ring.h:861
uint16_t virtId
Definition: udma_ring.h:151
int32_t Udma_ringProxyQueueRaw(Udma_RingHandle ringHandle, Udma_DrvHandle drvHandle, uint64_t phyDescMem)
void Udma_ringPrimeRead(Udma_RingHandle ringHandle, uint64_t *phyDescMem)
UDMA read descriptor from a exposed/"RING" mode ring - raw version (Reads physical pointers)....
uint16_t Udma_ringGetNum(Udma_RingHandle ringHandle)
Returns the ring number allocated for this ring.
UDMA ring monitor data.
Definition: udma_ring.h:232
UDMA ring monitor object.
Definition: udma_ring.h:860
UDMA ring monitor parameters.
Definition: udma_ring.h:199
UDMA ring object.
Definition: udma_ring.h:788
UDMA ring parameters.
Definition: udma_ring.h:134