xref: /illumos-gate/usr/src/boot/efi/include/Protocol/Decompress.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   The Decompress Protocol Interface as defined in UEFI spec
3 
4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5   SPDX-License-Identifier: BSD-2-Clause-Patent
6 
7 **/
8 
9 #ifndef __DECOMPRESS_H__
10 #define __DECOMPRESS_H__
11 
12 #define EFI_DECOMPRESS_PROTOCOL_GUID \
13   { \
14     0xd8117cfe, 0x94a6, 0x11d4, {0x9a, 0x3a, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \
15   }
16 
17 typedef struct _EFI_DECOMPRESS_PROTOCOL EFI_DECOMPRESS_PROTOCOL;
18 
19 /**
20   The GetInfo() function retrieves the size of the uncompressed buffer
21   and the temporary scratch buffer required to decompress the buffer
22   specified by Source and SourceSize.  If the size of the uncompressed
23   buffer or the size of the scratch buffer cannot be determined from
24   the compressed data specified by Source and SourceData, then
25   EFI_INVALID_PARAMETER is returned.  Otherwise, the size of the uncompressed
26   buffer is returned in DestinationSize, the size of the scratch buffer is
27   returned in ScratchSize, and EFI_SUCCESS is returned.
28 
29   The GetInfo() function does not have a scratch buffer available to perform
30   a thorough checking of the validity of the source data. It just retrieves
31   the 'Original Size' field from the beginning bytes of the source data and
32   output it as DestinationSize.  And ScratchSize is specific to the decompression
33   implementation.
34 
35   @param  This            A pointer to the EFI_DECOMPRESS_PROTOCOL instance.
36   @param  Source          The source buffer containing the compressed data.
37   @param  SourceSize      The size, in bytes, of source buffer.
38   @param  DestinationSize A pointer to the size, in bytes, of the uncompressed buffer
39                           that will be generated when the compressed buffer specified
40                           by Source and SourceSize is decompressed.
41   @param  ScratchSize     A pointer to the size, in bytes, of the scratch buffer that
42                           is required to decompress the compressed buffer specified by
43                           Source and SourceSize.
44 
45   @retval  EFI_SUCCESS           The size of the uncompressed data was returned in DestinationSize
46                                  and the size of the scratch buffer was returned in ScratchSize.
47   @retval  EFI_INVALID_PARAMETER The size of the uncompressed data or the size of the scratch
48                                  buffer cannot be determined from the compressed data specified by
49                                  Source and SourceData.
50 
51 **/
52 typedef
53 EFI_STATUS
54 (EFIAPI *EFI_DECOMPRESS_GET_INFO)(
55   IN EFI_DECOMPRESS_PROTOCOL            *This,
56   IN   VOID                             *Source,
57   IN   UINT32                           SourceSize,
58   OUT  UINT32                           *DestinationSize,
59   OUT  UINT32                           *ScratchSize
60   );
61 
62 /**
63   The Decompress() function extracts decompressed data to its original form.
64 
65   This protocol is designed so that the decompression algorithm can be
66   implemented without using any memory services.  As a result, the
67   Decompress() function is not allowed to call AllocatePool() or
68   AllocatePages() in its implementation.  It is the caller's responsibility
69   to allocate and free the Destination and Scratch buffers.
70 
71   If the compressed source data specified by Source and SourceSize is
72   successfully decompressed into Destination, then EFI_SUCCESS is returned.
73   If the compressed source data specified by Source and SourceSize is not in
74   a valid compressed data format, then EFI_INVALID_PARAMETER is returned.
75 
76   @param  This            A pointer to the EFI_DECOMPRESS_PROTOCOL instance.
77   @param  Source          The source buffer containing the compressed data.
78   @param  SourceSize      The size of source data.
79   @param  Destination     On output, the destination buffer that contains
80                           the uncompressed data.
81   @param  DestinationSize The size of destination buffer. The size of destination
82                           buffer needed is obtained from GetInfo().
83   @param  Scratch         A temporary scratch buffer that is used to perform the
84                           decompression.
85   @param  ScratchSize     The size of scratch buffer. The size of scratch buffer needed
86                           is obtained from GetInfo().
87 
88   @retval  EFI_SUCCESS          Decompression completed successfully, and the uncompressed
89                                 buffer is returned in Destination.
90   @retval EFI_INVALID_PARAMETER The source buffer specified by Source and SourceSize is
91                                 corrupted (not in a valid compressed format).
92 
93 **/
94 typedef
95 EFI_STATUS
96 (EFIAPI *EFI_DECOMPRESS_DECOMPRESS)(
97   IN EFI_DECOMPRESS_PROTOCOL              *This,
98   IN     VOID                             *Source,
99   IN     UINT32                           SourceSize,
100   IN OUT VOID                             *Destination,
101   IN     UINT32                           DestinationSize,
102   IN OUT VOID                             *Scratch,
103   IN     UINT32                           ScratchSize
104   );
105 
106 ///
107 /// Provides a decompression service.
108 ///
109 struct _EFI_DECOMPRESS_PROTOCOL {
110   EFI_DECOMPRESS_GET_INFO      GetInfo;
111   EFI_DECOMPRESS_DECOMPRESS    Decompress;
112 };
113 
114 extern EFI_GUID  gEfiDecompressProtocolGuid;
115 
116 #endif
117