1 /*
2 * Copyright 2023 NXP
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7 #ifndef _FSL_JPEGDEC_H_
8 #define _FSL_JPEGDEC_H_
9
10 #include "fsl_common.h"
11
12 /*!
13 * @addtogroup jpegdec
14 * @{
15 */
16
17 /*******************************************************************************
18 * Definitions
19 ******************************************************************************/
20 #define JPEG_ALIGN_SIZE(size, align) (((size) + (align)-1U) & ~((align)-1U))
21
22 /*! @name Driver version */
23 /*@{*/
24 /*! @brief JPEG decoder driver version 2.0.0. */
25 #define FSL_JPEGDEC_DRIVER_VERSION (MAKE_VERSION(2, 0, 0))
26 /*@}*/
27
28 /*! @brief JPEG decoder structure definition. */
29 typedef struct
30 {
31 JPEGDEC_Type *core; /*!< Pointer to decoder core. */
32 JPGDECWRP_Type *wrapper; /*!< Pointer to decoder wrapper. */
33 } JPEG_DECODER_Type;
34
35 /*! @brief Error codes for the JPEG decoder driver. */
36 enum
37 {
38 kStatus_JPEGDEC_NotSupported =
39 MAKE_STATUS(kStatusGroup_JPEGDEC, 0), /*!< Unsupported pixel format or image resolution. */
40 };
41
42 /*!
43 * @brief JPEG decoding pixel format.
44 */
45 typedef enum _jpegdec_pixel_format
46 {
47 kJPEGDEC_PixelFormatYUV420 = 0U, /*!< YUV420 format, Y at first plane, UV at second plane. */
48 kJPEGDEC_PixelFormatYUV422 = 1U, /*!< YUV422, 1 planar in the YUYV sequence. */
49 kJPEGDEC_PixelFormatRGB = 2U, /*!< RGB packed format. */
50 kJPEGDEC_PixelFormatYUV444 = 3U, /*!< YUV444, 1 planar in the YUVYUV sequence. */
51 kJPEGDEC_PixelFormatGray = 4U, /*!< 8-bit or 12-bit gray scale. */
52 kJPEGDEC_PixelFormatReserved = 5U, /*!< Reserved. */
53 kJPEGDEC_PixelFormatYCCK = 6U, /*!< YCCK format. */
54 } jpegdec_pixel_format_t;
55
56 /*!
57 * @brief JPEG decoding pixel depth.
58 */
59 typedef enum _jpegdec_pixel_depth
60 {
61 kJPEGDEC_PixelDepth8Bit = 0U, /*!< 8-bit per pixel. */
62 kJPEGDEC_PixelDepth12Bit = 1U, /*!< 12-bit per pixel. */
63 } jpegdec_pixel_depth_t;
64
65 /*! @brief JPEG decoder configuration. */
66 typedef struct _jpegdec_decoder_config
67 {
68 uint32_t outBufAddr0; /*!< Base address for output frame buffer0. 16-byte aligned(4 LSBs are zero). */
69 uint32_t outBufAddr1; /*!< Base address for output frame buffer1, only used for YUV420 second plane. 16-byte
70 aligned(4 LSBs are zero). */
71 uint32_t outBufPitch : 16; /*!< Output buffer pitch. */
72 uint32_t : 16; /*!< Reserved. */
73 uint32_t jpegBufAddr; /*!< Base address of the JPEG stream buffer for decoding. 16-byte aligned(4 LSBs are
74 zero). */
75 uint32_t jpegBufSize; /*!< Size of the JPEG stream buffer. 1k-byte aligned(10 LSBs are zero). */
76 uint32_t height : 14; /*!< Image height in pixel. Max supported is 8K(2000h), must be integer times of 8. */
77 uint32_t : 2; /*!< Reserved. */
78 uint32_t width : 14; /*!< Image width in pixel. Max supported is 8K(2000h), must be integer times of 8. */
79 uint32_t : 2; /*!< Reserved. */
80 uint32_t : 2; /*!< Reserved. */
81 uint32_t pixelDepth : 1; /*!< Pixel depth, @ref jpegdec_pixel_depth_t. */
82 uint32_t pixelFormat : 4; /*!< The image pixel format, @ref jpegdec_pixel_format_t. */
83 uint32_t clearStreamBuf : 1; /*!< Set to true to clear the saved bit stream buffer. */
84 uint32_t autoStart : 1; /*!< Set to true to automatically start the decoding when this descriptor is switched on. */
85 uint32_t : 23; /*!< Reserved. */
86 } jpegdec_decoder_config_t;
87
88 /*!
89 * @brief JPEG decoder descriptor.
90 *
91 * This structure is used to configure the linked decoding descriptor for one or more slots in Single Bit Stream Repeat
92 * mode or Context Switch mode.
93 */
94 typedef struct _jpegdec_descpt
95 {
96 uint32_t nextDescptAddr; /*!< Address of the next decoding descriptor. */
97 jpegdec_decoder_config_t config; /*!< The decoding configuration for this descriptor. */
98 } jpegdec_descpt_t;
99
100 /*! @brief Decoder slot Interrupt status and enable/disable flags. */
101 enum _jpegdec_flags
102 {
103 kJPEGDEC_StreamBufferHalfDoneFlag = (1U << 0U), /*!< Slot's bit stream buffer pointer has passed half the size. */
104 kJPEGDEC_StreamBufferDoneFlag = (1U << 1U), /*!< Slot's bit stream buffer pointer has finished. */
105 kJPEGDEC_SwitchInFlag = (1U << 2U), /*!< Current slot is switched in. */
106 kJPEGDEC_DecodeCompleteFlag = (1U << 3U), /*!< Current slot finished decoding. */
107 kJPEGDEC_DecodeErrorFlag = (1U << 8U), /*!< Current slot has error during decoding. */
108 kJPEGDEC_DescptReadErrorFlag = (1U << 9U), /*!< Descriptor read error when switching in current slot. */
109 kJPEGDEC_BitReadErrorFlag = (1U << 10U), /*!< Read JPEG stream error. */
110 kJPEGDEC_PixelWriteErrorFlag = (1U << 11U), /*!< Write decoded pixel error. */
111
112 kJPEGDEC_ErrorFlags = kJPEGDEC_DecodeErrorFlag | kJPEGDEC_DescptReadErrorFlag | kJPEGDEC_BitReadErrorFlag |
113 kJPEGDEC_PixelWriteErrorFlag,
114
115 kJPEGDEC_AllFlags = kJPEGDEC_StreamBufferHalfDoneFlag | kJPEGDEC_StreamBufferDoneFlag | kJPEGDEC_SwitchInFlag |
116 kJPEGDEC_DecodeCompleteFlag | kJPEGDEC_ErrorFlags,
117 };
118
119 /*! @brief JPEG decoding Slot. */
120 enum _jpegdec_slots
121 {
122 kJPEGDEC_Slot0 = (1U << 0U), /*!< Decoding slot 0. */
123 kJPEGDEC_Slot1 = (1U << 1U), /*!< Decoding slot 1. */
124 kJPEGDEC_Slot2 = (1U << 2U), /*!< Decoding slot 2. */
125 kJPEGDEC_Slot3 = (1U << 3U), /*!< Decoding slot 3. */
126 };
127
128 /*!
129 * @brief JPEG stream data format.
130 */
131 typedef enum _jpegdec_endian_mode
132 {
133 kJPEGDEC_BigEndian = 0U, /*!< JPEG data format is big endian. */
134 kJPEGDEC_LittleEndian = 1U, /*!< JPEG data format is little endian. */
135 } jpegdec_endian_mode_t;
136
137 /*! @brief Configuration for JPEG decoder. */
138 typedef struct _jpegdec_config
139 {
140 bool enable; /*!< Enables the decode IP. */
141 bool enableLp; /*!< Enables the core to enter low power mode. */
142 jpegdec_endian_mode_t endianMode; /*!< Endian mode for the souce/decoded image.*/
143 uint8_t slots; /*!< Mask of enabled slots @ref _jpegdec_slots. */
144 } jpegdec_config_t;
145
146 #if defined(__cplusplus)
147 extern "C" {
148 #endif
149
150 /*******************************************************************************
151 * API
152 ******************************************************************************/
153 /*!
154 * @name Initialization and deinitialization
155 * @{
156 */
157 /*!
158 * @brief Gets the default configuration for JPEG decoder.
159 *
160 * This function initializes the user configuration structure to default value. The default value are:
161 *
162 * Example:
163 @code
164 config->endianMode = kJPEGDEC_LittleEndian;
165 config->slots = 0xFU;
166 config->enable = true;
167 config->enableLp = false;
168 @endcode
169 *
170 * @param config Pointer to JPEG decoder configuration structure.
171 */
172 void JPEGDEC_GetDefaultConfig(jpegdec_config_t *config);
173
174 /*!
175 * @brief Initializes the JPEG decoder.
176 *
177 * The default configuration can be got by calling @ref JPEGDEC_GetDefaultConfig.
178 *
179 * @param base JPEG decoder peripheral base address.
180 * @param config Pointer to JPEG decoder configuration structure.
181 */
182 void JPEGDEC_Init(JPEG_DECODER_Type *base, const jpegdec_config_t *config);
183
184 /*!
185 * @brief Deinitializes the JPEG decoder.
186 *
187 * @param base JPEG decoder peripheral base address.
188 */
189 void JPEGDEC_Deinit(JPEG_DECODER_Type *base);
190 /* @} */
191
192 /*!
193 * @name Interrupts
194 * @{
195 */
196 /*!
197 * @brief Enables interrupts for certain slot.
198 *
199 * @param base JPEG decoder peripheral base address.
200 * @param slot Slot number.
201 * @param mask Interrupts mask formed by flags OR'ed together. @ref _jpegdec_flags.
202 */
JPEGDEC_EnableInterrupts(JPEG_DECODER_Type * base,uint8_t slot,uint32_t mask)203 static inline void JPEGDEC_EnableInterrupts(JPEG_DECODER_Type *base, uint8_t slot, uint32_t mask)
204 {
205 base->wrapper->SLOT_REGS[slot].SLOT_IRQ_EN |= mask;
206 }
207
208 /*!
209 * @brief Disables interrupts for certain slot.
210 *
211 * @param base JPEG decoder peripheral base address.
212 * @param slot Slot number.
213 * @param mask Interrupts mask formed by flags OR'ed together. @ref _jpegdec_flags.
214 */
JPEGDEC_DisableInterrupts(JPEG_DECODER_Type * base,uint8_t slot,uint32_t mask)215 static inline void JPEGDEC_DisableInterrupts(JPEG_DECODER_Type *base, uint8_t slot, uint32_t mask)
216 {
217 base->wrapper->SLOT_REGS[slot].SLOT_IRQ_EN &= ~mask;
218 }
219 /* @} */
220
221 /*!
222 * @name Status
223 * @{
224 */
225 /*!
226 * @brief Gets status flags for certain slot.
227 *
228 * @param base JPEG decoder peripheral base address.
229 * @param slot Slot number.
230 * @return Status flags asserted mask formed by flags OR'ed together. See "_jpegdec_flags".
231 */
JPEGDEC_GetStatusFlags(JPEG_DECODER_Type * base,uint8_t slot)232 static inline uint32_t JPEGDEC_GetStatusFlags(JPEG_DECODER_Type *base, uint8_t slot)
233 {
234 return base->wrapper->SLOT_REGS[slot].SLOT_STATUS;
235 }
236
237 /*!
238 * @brief Clears status flags for certain slot.
239 *
240 * @param base JPEG decoder peripheral base address.
241 * @param slot Slot number.
242 * @param mask Status flags mask formed by flags OR'ed together. See "_jpegdec_flags".
243 */
JPEGDEC_ClearStatusFlags(JPEG_DECODER_Type * base,uint8_t slot,uint32_t mask)244 static inline void JPEGDEC_ClearStatusFlags(JPEG_DECODER_Type *base, uint8_t slot, uint32_t mask)
245 {
246 base->wrapper->SLOT_REGS[slot].SLOT_STATUS = mask;
247 }
248 /* @} */
249
250 /*!
251 * @name Basic Operations
252 * @{
253 */
254 /*!
255 * @brief Enables the JPEG decoder module
256 *
257 * @param base JPEG decoder peripheral base address.
258 * @param enable True to enable, false to disable.
259 */
JPEGDEC_Enable(JPEG_DECODER_Type * base,bool enable)260 static inline void JPEGDEC_Enable(JPEG_DECODER_Type *base, bool enable)
261 {
262 if (enable)
263 {
264 base->wrapper->GLB_CTRL |= JPGDECWRP_GLB_CTRL_JPG_DEC_EN_MASK;
265 base->core->CTRL |= JPEGDEC_CTRL_GO_MASK;
266 }
267 else
268 {
269 base->wrapper->GLB_CTRL &= ~JPGDECWRP_GLB_CTRL_JPG_DEC_EN_MASK;
270 base->core->CTRL &= ~JPEGDEC_CTRL_GO_MASK;
271 }
272 }
273
274 /*!
275 * @brief Enables the JPEG decoder core to enter low power mode
276 *
277 * @param base JPEG decoder peripheral base address.
278 * @param enable True to enable, false to disable.
279 */
JPEGDEC_EnableLp(JPEG_DECODER_Type * base,bool enable)280 static inline void JPEGDEC_EnableLp(JPEG_DECODER_Type *base, bool enable)
281 {
282 if (enable)
283 {
284 base->core->CTRL |= JPEGDEC_CTRL_LP_MASK;
285 }
286 else
287 {
288 base->core->CTRL &= ~JPEGDEC_CTRL_LP_MASK;
289 }
290 }
291
292 /*!
293 * @brief Resets the JPEG decoder.
294 *
295 * @param base JPEG decoder peripheral base address.
296 */
JPEGDEC_Reset(JPEG_DECODER_Type * base)297 static inline void JPEGDEC_Reset(JPEG_DECODER_Type *base)
298 {
299 base->wrapper->GLB_CTRL |= JPGDECWRP_GLB_CTRL_SFTRST_MASK;
300 base->core->CTRL |= JPEGDEC_CTRL_SWR_MASK;
301 base->core->CTRL &= ~JPEGDEC_CTRL_SWR_MASK;
302 }
303
304 /*!
305 * @brief Starts the JPEG decode
306 *
307 * After calling this API the JPEG decoder will start decoding on a frame basis. The decoding process stops
308 * after the frame decoding is complete and if there are no other valid descriptors available. Auto-clear.
309 *
310 * @param base JPEG decoder peripheral base address.
311 */
JPEGDEC_StartDecode(JPEG_DECODER_Type * base)312 static inline void JPEGDEC_StartDecode(JPEG_DECODER_Type *base)
313 {
314 base->wrapper->GLB_CTRL |= JPGDECWRP_GLB_CTRL_DEC_GO_MASK;
315 }
316
317 /*!
318 * @brief Enables the JPEG decoding slot(s)
319 *
320 * @param base JPEG decoder peripheral base address.
321 * @param slot Masks of the enabled slot, @ref _jpegdec_slots.
322 */
JPEGDEC_EnableSlots(JPEG_DECODER_Type * base,uint8_t slots)323 static inline void JPEGDEC_EnableSlots(JPEG_DECODER_Type *base, uint8_t slots)
324 {
325 base->wrapper->GLB_CTRL |= (base->wrapper->GLB_CTRL & ~JPGDECWRP_GLB_CTRL_SLOT_EN_MASK) | JPGDECWRP_GLB_CTRL_SLOT_EN((uint32_t)slots);
326 }
327
328 /*!
329 * @brief Gets the current active slot
330 *
331 * @param base JPEG decoder peripheral base address.
332 * @param[out] slot Pointer to the variable that stores the enabled slot.
333 * @retval #kStatus_Success Successfully get the current active slot.
334 * @retval #kStatus_Fail Current JPEG decoder is idle, no slot is active.
335 */
336 status_t JPEGDEC_GetActiveSlot(JPEG_DECODER_Type *base, uint8_t *slot);
337
338 /*!
339 * @brief Sets the JPEG decoder endian mode for decoded data.
340 *
341 * @param base JPEG decoder peripheral base address.
342 * @param mode Endian mode.
343 */
JPEGDEC_SetEndian(JPEG_DECODER_Type * base,jpegdec_endian_mode_t mode)344 static inline void JPEGDEC_SetEndian(JPEG_DECODER_Type *base, jpegdec_endian_mode_t mode)
345 {
346 if (mode == kJPEGDEC_LittleEndian)
347 {
348 base->wrapper->GLB_CTRL |= JPGDECWRP_GLB_CTRL_L_ENDIAN_MASK;
349 }
350 else
351 {
352 base->wrapper->GLB_CTRL &= ~JPGDECWRP_GLB_CTRL_L_ENDIAN_MASK;
353 }
354 }
355 /* @} */
356
357 /*!
358 * @name Image decode
359 * @{
360 */
361 /*!
362 * @brief Sets the address and length of the JPEG image.
363 *
364 * @param[out] config Decoder configuration.
365 * @param data Start address of the buffer of the raw JPEG image, shall be 8-byte aligned.
366 * @param length Size of the buffer.
367 */
368 void JPEGDEC_SetJpegBuffer(jpegdec_decoder_config_t *config, uint8_t *buffer, size_t length);
369
370 /*!
371 * @brief Sets the address of the decoded data.
372 *
373 * @param[out] config Decoder configuration.
374 * @param imageData0 Address of the output buffer0, shall be 16-byte aligned.
375 * @param imageData1 Address of the output buffer1, only used when output format is YUV420, shall be 16-byte aligned.
376 */
377 void JPEGDEC_SetOutputBuffer(jpegdec_decoder_config_t *config, uint8_t *imageData0, uint8_t *imageData1);
378
379 /*!
380 * @brief Parses the JPEG header and stores the info in the decoder configuration structure.
381 *
382 * @param[out] config Decoder configuration.
383 * @retval kStatus_Success Header parsing success.
384 * @retval kStatus_Fail JPEG header parsing failed due corrupted header.
385 * @retval kStatus_JPEGDEC_NotSupported Header parsing failed due to the image pixel format is not supported
386 or image width/height is larger than 8k or image width/height is not 8-byte aligned.
387 */
388 status_t JPEGDEC_ParseHeader(jpegdec_decoder_config_t *config);
389
390 /*!
391 * @brief Sets the decode option.
392 *
393 * @param[out] config Decoder configuration.
394 * @param pitch Output buffer pitch.
395 * @param clearStreamBuf Set to true to clear the saved bit stream buffer, not used in single frame mode.
396 * @param autoStart Set to true to automatically start the decoding when this descriptor is switched on, not used in
397 single frame mode.
398 */
399 void JPEGDEC_SetDecodeOption(jpegdec_decoder_config_t *config, uint16_t pitch, bool clearStreamBuf, bool autoStart);
400
401 /*!
402 * @brief Sets JPEG decoder decoder configuration.
403 *
404 * Call this API to set the decoder configuration and then call @ref JPEGDEC_StartDecode
405 * to start decode. Need to enable at least one slot in @ref jpegdec_config_t first.
406 *
407 * @param base JPEG decoder peripheral base address.
408 * @param config Decoder configuration.
409 */
410 void JPEGDEC_ConfigDecoder(JPEG_DECODER_Type *base, const jpegdec_decoder_config_t *config);
411
412 /*!
413 * @brief Sets the address of the next decoder descriptor for certain slot.
414 *
415 * Call this API to set the decoder descriptor for certain slot, and then call
416 * @ref JPEGDEC_EnableSlotNextDescpt to enable the descriptor. If the decode configuration
417 * of this descriptor has enabled autoStart then decode will start automatically.
418 * Otherwise user has to call @ref JPEGDEC_StartDecode manually. Need to enable the
419 * slot in @ref jpegdec_config_t first.
420 *
421 * @param base JPEG decoder peripheral base address.
422 * @param slot Slot number.
423 * @param descriptor Pointer to the descriptor structure.
424 */
425 void JPEGDEC_SetSlotNextDescpt(JPEG_DECODER_Type *base, uint8_t slot, jpegdec_descpt_t *descriptor);
426
427 /*!
428 * @brief Enables the next decoder descriptor for certain slot.
429 *
430 * Call this API after calling JPEGDEC_SetSlotNextDescpt to set valid descriptor for certain slot.
431 * User can also call @ref JPEGDEC_EnableLinkedDescpt before calling @ref JPEGDEC_SetSlotNextDescpt,
432 * then the descriptor will be loaded automatically.
433 *
434 * @param base JPEG decoder peripheral base address.
435 * @param slot Slot number.
436 */
JPEGDEC_EnableSlotNextDescpt(JPEG_DECODER_Type * base,uint8_t slot)437 static inline void JPEGDEC_EnableSlotNextDescpt(JPEG_DECODER_Type *base, uint8_t slot)
438 {
439 base->wrapper->SLOT_REGS[slot].SLOT_NXT_DESCPT_PTR |= JPGDECWRP_SLOT_NXT_DESCPT_PTR_NXT_DESCPT_EN_MASK;
440 }
441
442 /*!
443 * @brief Enables the next linked descriptor.
444 *
445 * Call this API before calling @ref JPEGDEC_SetSlotNextDescpt, then the descriptor will be loaded
446 * automatically. Otherwise call @ref JPEGDEC_EnableSlotNextDescpt after calling @ref JPEGDEC_SetSlotNextDescpt.
447 *
448 * @param[out] descriptor Pointer to the descriptor structure.
449 */
JPEGDEC_EnableLinkedDescpt(jpegdec_descpt_t * descriptor)450 static inline void JPEGDEC_EnableLinkedDescpt(jpegdec_descpt_t *descriptor)
451 {
452 /* The 1LSB for nextDescptAddr is used to specify the */
453 descriptor->nextDescptAddr |= 0x1U;
454 }
455
456 /*!
457 * @brief Sets all fields to default values for the descriptor structure.
458 *
459 * @param descriptor Pointer to the descriptor structure.
460 * @note This function enables the auto start feature.
461 */
462 void JPEGDEC_DescptReset(jpegdec_descpt_t *descriptor);
463 /* @} */
464
465 #if defined(__cplusplus)
466 }
467 #endif
468
469 /*! @}*/
470
471 #endif /* _FSL_JPEGDEC_H_ */
472
