source: svn/trunk/newcon3bcm2_21bu/magnum/commonutils/udp/budp_bitread.h @ 23

Last change on this file since 23 was 2, checked in by jglee, 11 years ago

first commit
  • Property svn:executable set to *
File size: 7.0 KB
Line 
1/***************************************************************************
2 *     Copyright (c) 2003-2010, Broadcom Corporation
3 *     All Rights Reserved
4 *     Confidential Property of Broadcom Corporation
5 *
6 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
7 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
8 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
9 *
10 * $brcm_Workfile: budp_bitread.h $
11 * $brcm_Revision: Hydra_Software_Devel/1 $
12 * $brcm_Date: 7/27/10 5:05p $
13 *
14 * Module Description:
15 *
16 * Revision History:
17 *
18 * $brcm_Log: /magnum/commonutils/udp/budp_bitread.h $
19 *
20 * Hydra_Software_Devel/1   7/27/10 5:05p darnstein
21 * SW3548-3022: userdata parsing software.
22 *
23 ***************************************************************************/
24
25/*= Module Overview *********************************************************
26<verbatim>
27
28Overview
29BUDP_Bitread module eases reading through memory a few bits at a time.  It
30only accesses the memory on 4-byte boundaries.  This restriction is necessary
31to read the MPEG userdata that BMVD_USERDATA_Read() returns.
32
33</verbatim>
34***************************************************************************/
35
36#ifndef BUDPBITREAD_H__
37#define BUDPBITREAD_H__
38
39#include "bstd.h"
40#include "berr.h"
41#include "budp.h"
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47
48/*****************************************************************************
49        Module specific standard BERR codes
50 *****************************************************************************/
51
52/*****************************************************************************
53 * Structures
54 *****************************************************************************/
55
56/*****************************************************************************
57  Summary:
58    Context for BUDP_Bitread object
59   
60  Description:
61    The BUDP_Bitread_Context, once initielized, represents the state of the
62        BUDP_Bitread object.
63
64  See Also:
65    BUDP_Bitread_Init
66 *****************************************************************************/
67typedef struct
68{
69        uint32_t*    userdata_start;
70        uint32_t*    userdata;
71        uint32_t     cache;
72        unsigned int bitsleft;
73        bool         bByteswap;
74}
75BUDP_Bitread_Context;
76
77
78/*****************************************************************************
79 * Public API
80 *****************************************************************************/
81
82
83/*****************************************************************************
84  Summary:
85    Initialize a BUDP_Bitread context.
86
87  Description:
88    This function intializes a BUDP_Bitread context.  It does not
89        allocate space for the context, though.
90
91        This function reads from the address userdata (function argument).  If
92        this address is not a multiple of four, then the function will read from
93        the closest, lesser address that is a multiple of four.  Note that this can
94        lead to memory access violations and crashes!  It is most reliable to
95        simply feed this function userdata that starts at an address that is a
96        multiple of four.
97
98  Returns:
99        BERR_SUCCESS              - The context was successfully initialized.
100        BERR_INVALID_PARAMETER    - One of the supplied parameters was invalid,
101                                                            possibly NULL.
102        BERR_OUT_OF_SYSTEM_MEMORY - Memory allocation failed.
103
104  See Also:
105 *****************************************************************************/
106BERR_Code BUDP_Bitread_Init( 
107        BUDP_Bitread_Context* 
108             pBitreadContext,   /*  [in] A pointer to a BUDP_Bitread_Context. */
109        bool       bByteswap,   /*  [in] Whether or not to do -endian
110                                         conversion.                             */
111        void* userdata_start    /*  [in] The data to be read by future calls
112                                         into the object.  See above discussion
113                                                                     regarding the alignment of this value.  */
114); 
115
116
117/*****************************************************************************
118  Summary:
119    Read bits from a BUDP_Bitread_Context.
120
121  Description:
122    This function reads bits from an initialized BUDP_Bitread_Context. 
123        Up to 32 bits of data may be read at a time.
124
125  Returns:
126        The specified number of bits from the input context.  The bits are right-
127        justified.
128
129  See Also:
130    BUDP_Bitread_Byte
131 *****************************************************************************/
132uint32_t BUDP_Bitread_Read(
133        BUDP_Bitread_Context*   pContext,       /* [in] A valid BUDP_Bitread
134                                                      context.                   */
135        unsigned int               nbits        /* [in] The number of bits to read.  */
136); 
137
138
139/*****************************************************************************
140  Summary:
141    Read a byte (8 bits) from a BUDP_Bitread_Context.
142
143  Description:
144    This function reads 8 bits from an initialized BUDP_Bitread_Context. 
145        This function is faster than BUDP_Bitread_Read().
146
147  Returns:
148        The byte from the input context.  Right-justified.
149
150  See Also:
151    BUDP_Bitread_Read
152 *****************************************************************************/
153uint32_t BUDP_Bitread_Byte(
154    BUDP_Bitread_Context*   pContext    /* [in] A valid
155                                                                                    BUDP_Bitread context. */   
156);
157
158
159/*****************************************************************************
160  Summary:
161    Returns byte (not bit) position of an initialized BUDP_Bitread_Context.
162
163  Description:
164    This function discloses the next byte position to be read in a
165        BUDP_Bitread_Context. Note that the BUDP_Bitread_Context maintains a
166        bit position as part of its state. If this bit position is not an integer
167        multiple of 8 bits, then conceptually, some information is lost.
168
169  Returns:
170        The byte offset of the object.
171
172  See Also:
173    BUDP_Bitread_Init
174 *****************************************************************************/
175uint32_t BUDP_Bitread_GetByteOffset(
176    BUDP_Bitread_Context*   pContext    /* [in] A valid BUDP_Bitread
177                                                    context.                     */
178);
179
180
181/*****************************************************************************
182  Summary:
183    Implements the MPEG next_start_code() function on a
184        BUDP_Bitread_Context.
185
186  Description:
187        This function reads bytes from a BUDP_Bitread_Context until an MPEG
188        start code is found. Then, it "rewinds" the BUDP_Bitread_Context by four
189        bytes. If no start code is found, the BUDP_Bitread_Context is left at
190        the end of the search range, and a value of zero is returned.
191
192        The caller provides a length (in bytes) to prevent an infinite search loop.
193
194  Returns:
195    The full 32-bit MPEG startcode.
196
197  See Also:
198    BUDP_Bitread_Init
199 *****************************************************************************/
200uint32_t BUDP_Bitread_next_start_code(
201    BUDP_Bitread_Context* pContext, /*  [in] A valid BUDP_Bitread context. */
202         size_t                 length, /*  [in] How many bytes to search
203                                                 forward.                      */
204        size_t*           pBytesParsed  /* [out] How many bytes were read      */
205);
206
207
208#ifdef __cplusplus
209}
210#endif
211 
212#endif /* BUDPBITREAD_H__ */
Note: See TracBrowser for help on using the repository browser.