1 /*
2  * SPDX-FileCopyrightText: Copyright (c) 1993-2023 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3  * SPDX-License-Identifier: MIT
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a
6  * copy of this software and associated documentation files (the "Software"),
7  * to deal in the Software without restriction, including without limitation
8  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9  * and/or sell copies of the Software, and to permit persons to whom the
10  * Software is furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
18  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21  * DEALINGS IN THE SOFTWARE.
22  */
23 
24 #ifndef _BINDATA_H
25 #define _BINDATA_H
26 
27 #include "core/core.h"
28 
29 /**************************************************************************************************************
30 *
31 *    File:  bindata.h
32 *
33 *    Description:
34 *        Bindata management APIs
35 *
36 **************************************************************************************************************/
37 
38 //
39 // Public interface for accessing the acquired binary data
40 //
41 
42 //
43 // Binary data access handler
44 //
45 typedef struct BINDATA_RUNTIME_INFO BINDATA_RUNTIME_INFO, *PBINDATA_RUNTIME_INFO;
46 
47 //
48 // Public binary storage information
49 //
50 struct BINDATA_STORAGE;         // currently no public data fields
51 typedef struct BINDATA_STORAGE BINDATA_STORAGE, *PBINDATA_STORAGE;
52 
53 
54 //
55 // Primitives
56 //
57 NV_STATUS bindataAcquire(const BINDATA_STORAGE *pBinStorage, PBINDATA_RUNTIME_INFO *ppBinInfo);
58 NV_STATUS bindataGetNextChunk(PBINDATA_RUNTIME_INFO pBinInfo, NvU8 *pBuffer, NvU32 nBytes);
59 void      bindataRelease(PBINDATA_RUNTIME_INFO pBinInfo);
60 
61 
62 //
63 // Utilities
64 //
65 NV_STATUS bindataWriteToBuffer(const BINDATA_STORAGE *pBinStorage, NvU8 *pBuffer, NvU32 bufferSize);
66 NvU32     bindataGetBufferSize(const BINDATA_STORAGE *pBinStorage);
67 NV_STATUS bindataStorageAcquireData(const BINDATA_STORAGE *pBinStorage, const void **ppData);
68 void bindataStorageReleaseData(void *pData);
69 
70 void bindataInitialize(void);
71 void bindataDestroy(void);
72 
73 //
74 // Bindata Archive support
75 //
76 typedef struct
77 {
78     const char*              name;                // string of file name or name tag
79     const PBINDATA_STORAGE   pBinStorage;         // pointer to the binary storage
80 } BINDATA_ARCHIVE_ENTRY;
81 
82 typedef struct
83 {
84     NvU32 entryNum;
85     BINDATA_ARCHIVE_ENTRY entries[];
86 } BINDATA_ARCHIVE;
87 
88 
89 // Bindata Archive API - get Bindata storage from a Bindata Archive
90 const BINDATA_STORAGE * bindataArchiveGetStorage(const BINDATA_ARCHIVE *pBinArchive, const char *bindataName);
91 
92 //
93 // Iterate over all BINDATA_STORAGE entries that have not been referenced so far
94 // Returns the pointer to unreferenced data or NULL if no more are available.
95 // Example usage:
96 //    const BINDATA_STORAGE *iter = NULL;
97 //    void *datablock;
98 //    NvU32 size;
99 //    while ((datablock = bindataGetNextUnreferencedStorage(&iter, &size))) {
100 //        do_stuff(datablock, size);
101 //    }
102 //
103 void* bindataGetNextUnreferencedStorage(const BINDATA_STORAGE **iter, NvU32 *pDataSize);
104 //
105 // Marks a given BINDATA_STORAGE as destroyed, making all subsequent attempts
106 // to access it fail and return NULL/0
107 //
108 void bindataDestroyStorage(BINDATA_STORAGE *storage);
109 
110 #endif // _BINDATA_H
111