[mirror_edk2.git] / MdeModulePkg / Bus / Sd / SdDxe / SdBlockIo.h

/** @file\r
  Header file for SdDxe Driver.\r
\r
  This file defines common data structures, macro definitions and some module\r
  internal function header files.\r
\r
  Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>\r
  This program and the accompanying materials\r
  are licensed and made available under the terms and conditions of the BSD License\r
  which accompanies this distribution.  The full text of the license may be found at\r
  http://opensource.org/licenses/bsd-license.php\r
\r
  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _SD_BLOCK_IO_H_\r
#define _SD_BLOCK_IO_H_\r
\r
/**\r
  Reset the Block Device.\r
\r
  @param  This                 Indicates a pointer to the calling context.\r
  @param  ExtendedVerification Driver may perform diagnostics on reset.\r
\r
  @retval EFI_SUCCESS          The device was reset.\r
  @retval EFI_DEVICE_ERROR     The device is not functioning properly and could\r
                               not be reset.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdReset (\r
  IN  EFI_BLOCK_IO_PROTOCOL   *This,\r
  IN  BOOLEAN                 ExtendedVerification\r
  );\r
\r
/**\r
  Read BufferSize bytes from Lba into Buffer.\r
\r
  @param  This       Indicates a pointer to the calling context.\r
  @param  MediaId    Id of the media, changes every time the media is replaced.\r
  @param  Lba        The starting Logical Block Address to read from\r
  @param  BufferSize Size of Buffer, must be a multiple of device block size.\r
  @param  Buffer     A pointer to the destination buffer for the data. The caller is\r
                     responsible for either having implicit or explicit ownership of the buffer.\r
\r
  @retval EFI_SUCCESS           The data was read correctly from the device.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing the read.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHANGED     The MediaId does not matched the current device.\r
  @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
  @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdReadBlocks (\r
  IN     EFI_BLOCK_IO_PROTOCOL  *This,\r
  IN     UINT32                 MediaId,\r
  IN     EFI_LBA                Lba,\r
  IN     UINTN                  BufferSize,\r
     OUT VOID                   *Buffer\r
  );\r
\r
/**\r
  Write BufferSize bytes from Lba into Buffer.\r
\r
  @param  This       Indicates a pointer to the calling context.\r
  @param  MediaId    The media ID that the write request is for.\r
  @param  Lba        The starting logical block address to be written. The caller is\r
                     responsible for writing to only legitimate locations.\r
  @param  BufferSize Size of Buffer, must be a multiple of device block size.\r
  @param  Buffer     A pointer to the source buffer for the data.\r
\r
  @retval EFI_SUCCESS           The data was written correctly to the device.\r
  @retval EFI_WRITE_PROTECTED   The device can not be written to.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.\r
  @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
  @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdWriteBlocks (\r
  IN  EFI_BLOCK_IO_PROTOCOL   *This,\r
  IN  UINT32                  MediaId,\r
  IN  EFI_LBA                 Lba,\r
  IN  UINTN                   BufferSize,\r
  IN  VOID                    *Buffer\r
  );\r
\r
/**\r
  Flush the Block Device.\r
\r
  @param  This              Indicates a pointer to the calling context.\r
\r
  @retval EFI_SUCCESS       All outstanding data was written to the device\r
  @retval EFI_DEVICE_ERROR  The device reported an error while writing back the data\r
  @retval EFI_NO_MEDIA      There is no media in the device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdFlushBlocks (\r
  IN  EFI_BLOCK_IO_PROTOCOL   *This\r
  );\r
\r
/**\r
  Reset the Block Device.\r
\r
  @param[in]  This                 Indicates a pointer to the calling context.\r
  @param[in]  ExtendedVerification Driver may perform diagnostics on reset.\r
\r
  @retval EFI_SUCCESS              The device was reset.\r
  @retval EFI_DEVICE_ERROR         The device is not functioning properly and could\r
                                   not be reset.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdResetEx (\r
  IN  EFI_BLOCK_IO2_PROTOCOL  *This,\r
  IN  BOOLEAN                 ExtendedVerification\r
  );\r
\r
/**\r
  Read BufferSize bytes from Lba into Buffer.\r
\r
  @param[in]       This         Indicates a pointer to the calling context.\r
  @param[in]       MediaId      Id of the media, changes every time the media is replaced.\r
  @param[in]       Lba          The starting Logical Block Address to read from.\r
  @param[in, out]  Token        A pointer to the token associated with the transaction.\r
  @param[in]       BufferSize   Size of Buffer, must be a multiple of device block size.\r
  @param[out]      Buffer       A pointer to the destination buffer for the data. The caller is\r
                                responsible for either having implicit or explicit ownership of the buffer.\r
\r
  @retval EFI_SUCCESS           The read request was queued if Event is not NULL.\r
                                The data was read correctly from the device if\r
                                the Event is NULL.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing\r
                                the read.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHANGED     The MediaId is not for the current media.\r
  @retval EFI_BAD_BUFFER_SIZE   The BufferSize parameter is not a multiple of the\r
                                intrinsic block size of the device.\r
  @retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
  @retval EFI_OUT_OF_RESOURCES  The request could not be completed due to a lack\r
                                of resources.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdReadBlocksEx (\r
  IN     EFI_BLOCK_IO2_PROTOCOL *This,\r
  IN     UINT32                 MediaId,\r
  IN     EFI_LBA                Lba,\r
  IN OUT EFI_BLOCK_IO2_TOKEN    *Token,\r
  IN     UINTN                  BufferSize,\r
     OUT VOID                   *Buffer\r
  );\r
\r
/**\r
  Write BufferSize bytes from Lba into Buffer.\r
\r
  @param[in]       This         Indicates a pointer to the calling context.\r
  @param[in]       MediaId      The media ID that the write request is for.\r
  @param[in]       Lba          The starting logical block address to be written. The\r
                                caller is responsible for writing to only legitimate\r
                                locations.\r
  @param[in, out]  Token        A pointer to the token associated with the transaction.\r
  @param[in]       BufferSize   Size of Buffer, must be a multiple of device block size.\r
  @param[in]       Buffer       A pointer to the source buffer for the data.\r
\r
  @retval EFI_SUCCESS           The data was written correctly to the device.\r
  @retval EFI_WRITE_PROTECTED   The device can not be written to.\r
  @retval EFI_DEVICE_ERROR      The device reported an error while performing the write.\r
  @retval EFI_NO_MEDIA          There is no media in the device.\r
  @retval EFI_MEDIA_CHNAGED     The MediaId does not matched the current device.\r
  @retval EFI_BAD_BUFFER_SIZE   The Buffer was not a multiple of the block size of the device.\r
  @retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
                                or the buffer is not on proper alignment.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdWriteBlocksEx (\r
  IN     EFI_BLOCK_IO2_PROTOCOL *This,\r
  IN     UINT32                 MediaId,\r
  IN     EFI_LBA                Lba,\r
  IN OUT EFI_BLOCK_IO2_TOKEN    *Token,\r
  IN     UINTN                  BufferSize,\r
  IN     VOID                   *Buffer\r
  );\r
\r
/**\r
  Flush the Block Device.\r
\r
  @param[in]       This     Indicates a pointer to the calling context.\r
  @param[in, out]  Token    A pointer to the token associated with the transaction.\r
\r
  @retval EFI_SUCCESS       All outstanding data was written to the device\r
  @retval EFI_DEVICE_ERROR  The device reported an error while writing back the data\r
  @retval EFI_NO_MEDIA      There is no media in the device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdFlushBlocksEx (\r
  IN     EFI_BLOCK_IO2_PROTOCOL  *This,\r
  IN OUT EFI_BLOCK_IO2_TOKEN     *Token\r
  );\r
\r
/**\r
  Erase a specified number of device blocks.\r
\r
  @param[in]       This           Indicates a pointer to the calling context.\r
  @param[in]       MediaId        The media ID that the erase request is for.\r
  @param[in]       Lba            The starting logical block address to be\r
                                  erased. The caller is responsible for erasing\r
                                  only legitimate locations.\r
  @param[in, out]  Token          A pointer to the token associated with the\r
                                  transaction.\r
  @param[in]       Size           The size in bytes to be erased. This must be\r
                                  a multiple of the physical block size of the\r
                                  device.\r
\r
  @retval EFI_SUCCESS             The erase request was queued if Event is not\r
                                  NULL. The data was erased correctly to the\r
                                  device if the Event is NULL.to the device.\r
  @retval EFI_WRITE_PROTECTED     The device cannot be erased due to write\r
                                  protection.\r
  @retval EFI_DEVICE_ERROR        The device reported an error while attempting\r
                                  to perform the erase operation.\r
  @retval EFI_INVALID_PARAMETER   The erase request contains LBAs that are not\r
                                  valid.\r
  @retval EFI_NO_MEDIA            There is no media in the device.\r
  @retval EFI_MEDIA_CHANGED       The MediaId is not for the current media.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
SdEraseBlocks (\r
  IN     EFI_ERASE_BLOCK_PROTOCOL      *This,\r
  IN     UINT32                        MediaId,\r
  IN     EFI_LBA                       Lba,\r
  IN OUT EFI_ERASE_BLOCK_TOKEN         *Token,\r
  IN     UINTN                         Size\r
  );\r
\r
#endif\r
\r
Commit	Line	Data
48555339 FT	1	/** @file\r
	2	Header file for SdDxe Driver.\r
	3	\r
	4	This file defines common data structures, macro definitions and some module\r
	5	internal function header files.\r
	6	\r
275d5136	7	Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR>\r
48555339 FT	8	This program and the accompanying materials\r
	9	are licensed and made available under the terms and conditions of the BSD License\r
	10	which accompanies this distribution. The full text of the license may be found at\r
	11	http://opensource.org/licenses/bsd-license.php\r
	12	\r
	13	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	14	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
	15	\r
	16	**/\r
	17	\r
	18	#ifndef _SD_BLOCK_IO_H_\r
	19	#define _SD_BLOCK_IO_H_\r
	20	\r
	21	/**\r
	22	Reset the Block Device.\r
	23	\r
	24	@param This Indicates a pointer to the calling context.\r
	25	@param ExtendedVerification Driver may perform diagnostics on reset.\r
	26	\r
	27	@retval EFI_SUCCESS The device was reset.\r
	28	@retval EFI_DEVICE_ERROR The device is not functioning properly and could\r
	29	not be reset.\r
	30	\r
	31	**/\r
	32	EFI_STATUS\r
	33	EFIAPI\r
	34	SdReset (\r
	35	IN EFI_BLOCK_IO_PROTOCOL *This,\r
	36	IN BOOLEAN ExtendedVerification\r
	37	);\r
	38	\r
	39	/**\r
	40	Read BufferSize bytes from Lba into Buffer.\r
	41	\r
	42	@param This Indicates a pointer to the calling context.\r
	43	@param MediaId Id of the media, changes every time the media is replaced.\r
	44	@param Lba The starting Logical Block Address to read from\r
	45	@param BufferSize Size of Buffer, must be a multiple of device block size.\r
	46	@param Buffer A pointer to the destination buffer for the data. The caller is\r
	47	responsible for either having implicit or explicit ownership of the buffer.\r
	48	\r
	49	@retval EFI_SUCCESS The data was read correctly from the device.\r
	50	@retval EFI_DEVICE_ERROR The device reported an error while performing the read.\r
	51	@retval EFI_NO_MEDIA There is no media in the device.\r
	52	@retval EFI_MEDIA_CHANGED The MediaId does not matched the current device.\r
	53	@retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.\r
	54	@retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
	55	or the buffer is not on proper alignment.\r
	56	\r
	57	**/\r
	58	EFI_STATUS\r
	59	EFIAPI\r
	60	SdReadBlocks (\r
	61	IN EFI_BLOCK_IO_PROTOCOL *This,\r
	62	IN UINT32 MediaId,\r
	63	IN EFI_LBA Lba,\r
	64	IN UINTN BufferSize,\r
	65	OUT VOID *Buffer\r
	66	);\r
	67	\r
	68	/**\r
	69	Write BufferSize bytes from Lba into Buffer.\r
	70	\r
	71	@param This Indicates a pointer to the calling context.\r
72	@param MediaId The media ID that the write request is for.\r
73	@param Lba The starting logical block address to be written. The caller is\r
74	responsible for writing to only legitimate locations.\r
75	@param BufferSize Size of Buffer, must be a multiple of device block size.\r
76	@param Buffer A pointer to the source buffer for the data.\r
77	\r
78	@retval EFI_SUCCESS The data was written correctly to the device.\r
79	@retval EFI_WRITE_PROTECTED The device can not be written to.\r
80	@retval EFI_DEVICE_ERROR The device reported an error while performing the write.\r
81	@retval EFI_NO_MEDIA There is no media in the device.\r
82	@retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device.\r
83	@retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.\r
84	@retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
85	or the buffer is not on proper alignment.\r
86	\r
87	**/\r
88	EFI_STATUS\r
89	EFIAPI\r
90	SdWriteBlocks (\r
91	IN EFI_BLOCK_IO_PROTOCOL *This,\r
92	IN UINT32 MediaId,\r
93	IN EFI_LBA Lba,\r
94	IN UINTN BufferSize,\r
95	IN VOID *Buffer\r
96	);\r
97	\r
98	/**\r
99	Flush the Block Device.\r
100	\r
101	@param This Indicates a pointer to the calling context.\r
102	\r
103	@retval EFI_SUCCESS All outstanding data was written to the device\r
104	@retval EFI_DEVICE_ERROR The device reported an error while writing back the data\r
105	@retval EFI_NO_MEDIA There is no media in the device.\r
106	\r
107	**/\r
108	EFI_STATUS\r
109	EFIAPI\r
110	SdFlushBlocks (\r
111	IN EFI_BLOCK_IO_PROTOCOL *This\r
112	);\r
113	\r
114	/**\r
115	Reset the Block Device.\r
116	\r
117	@param[in] This Indicates a pointer to the calling context.\r
118	@param[in] ExtendedVerification Driver may perform diagnostics on reset.\r
119	\r
120	@retval EFI_SUCCESS The device was reset.\r
121	@retval EFI_DEVICE_ERROR The device is not functioning properly and could\r
122	not be reset.\r
123	\r
124	**/\r
125	EFI_STATUS\r
126	EFIAPI\r
127	SdResetEx (\r
128	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
129	IN BOOLEAN ExtendedVerification\r
130	);\r
131	\r
132	/**\r
133	Read BufferSize bytes from Lba into Buffer.\r
134	\r
135	@param[in] This Indicates a pointer to the calling context.\r
136	@param[in] MediaId Id of the media, changes every time the media is replaced.\r
137	@param[in] Lba The starting Logical Block Address to read from.\r
138	@param[in, out] Token A pointer to the token associated with the transaction.\r
139	@param[in] BufferSize Size of Buffer, must be a multiple of device block size.\r
140	@param[out] Buffer A pointer to the destination buffer for the data. The caller is\r
141	responsible for either having implicit or explicit ownership of the buffer.\r
142	\r
143	@retval EFI_SUCCESS The read request was queued if Event is not NULL.\r
144	The data was read correctly from the device if\r
145	the Event is NULL.\r
146	@retval EFI_DEVICE_ERROR The device reported an error while performing\r
147	the read.\r
148	@retval EFI_NO_MEDIA There is no media in the device.\r
149	@retval EFI_MEDIA_CHANGED The MediaId is not for the current media.\r
150	@retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the\r
151	intrinsic block size of the device.\r
152	@retval EFI_INVALID_PARAMETER The read request contains LBAs that are not valid,\r
153	or the buffer is not on proper alignment.\r
154	@retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack\r
155	of resources.\r
156	\r
157	**/\r
158	EFI_STATUS\r
159	EFIAPI\r
160	SdReadBlocksEx (\r
161	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
162	IN UINT32 MediaId,\r
163	IN EFI_LBA Lba,\r
164	IN OUT EFI_BLOCK_IO2_TOKEN *Token,\r
165	IN UINTN BufferSize,\r
166	OUT VOID *Buffer\r
167	);\r
168	\r
169	/**\r
170	Write BufferSize bytes from Lba into Buffer.\r
171	\r
172	@param[in] This Indicates a pointer to the calling context.\r
173	@param[in] MediaId The media ID that the write request is for.\r
174	@param[in] Lba The starting logical block address to be written. The\r
175	caller is responsible for writing to only legitimate\r
176	locations.\r
177	@param[in, out] Token A pointer to the token associated with the transaction.\r
178	@param[in] BufferSize Size of Buffer, must be a multiple of device block size.\r
179	@param[in] Buffer A pointer to the source buffer for the data.\r
180	\r
181	@retval EFI_SUCCESS The data was written correctly to the device.\r
182	@retval EFI_WRITE_PROTECTED The device can not be written to.\r
183	@retval EFI_DEVICE_ERROR The device reported an error while performing the write.\r
184	@retval EFI_NO_MEDIA There is no media in the device.\r
185	@retval EFI_MEDIA_CHNAGED The MediaId does not matched the current device.\r
186	@retval EFI_BAD_BUFFER_SIZE The Buffer was not a multiple of the block size of the device.\r
187	@retval EFI_INVALID_PARAMETER The write request contains LBAs that are not valid,\r
188	or the buffer is not on proper alignment.\r
189	\r
190	**/\r
191	EFI_STATUS\r
192	EFIAPI\r
193	SdWriteBlocksEx (\r
194	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
195	IN UINT32 MediaId,\r
196	IN EFI_LBA Lba,\r
197	IN OUT EFI_BLOCK_IO2_TOKEN *Token,\r
198	IN UINTN BufferSize,\r
199	IN VOID *Buffer\r
200	);\r
201	\r
202	/**\r
203	Flush the Block Device.\r
204	\r
205	@param[in] This Indicates a pointer to the calling context.\r
206	@param[in, out] Token A pointer to the token associated with the transaction.\r
207	\r
208	@retval EFI_SUCCESS All outstanding data was written to the device\r
209	@retval EFI_DEVICE_ERROR The device reported an error while writing back the data\r
210	@retval EFI_NO_MEDIA There is no media in the device.\r
211	\r
212	**/\r
213	EFI_STATUS\r
214	EFIAPI\r
215	SdFlushBlocksEx (\r
216	IN EFI_BLOCK_IO2_PROTOCOL *This,\r
217	IN OUT EFI_BLOCK_IO2_TOKEN *Token\r
218	);\r
219	\r
275d5136 FT	220	/**\r
	221	Erase a specified number of device blocks.\r
	222	\r
	223	@param[in] This Indicates a pointer to the calling context.\r
	224	@param[in] MediaId The media ID that the erase request is for.\r
	225	@param[in] Lba The starting logical block address to be\r
	226	erased. The caller is responsible for erasing\r
	227	only legitimate locations.\r
	228	@param[in, out] Token A pointer to the token associated with the\r
	229	transaction.\r
	230	@param[in] Size The size in bytes to be erased. This must be\r
	231	a multiple of the physical block size of the\r
	232	device.\r
	233	\r
	234	@retval EFI_SUCCESS The erase request was queued if Event is not\r
	235	NULL. The data was erased correctly to the\r
	236	device if the Event is NULL.to the device.\r
	237	@retval EFI_WRITE_PROTECTED The device cannot be erased due to write\r
	238	protection.\r
	239	@retval EFI_DEVICE_ERROR The device reported an error while attempting\r
	240	to perform the erase operation.\r
	241	@retval EFI_INVALID_PARAMETER The erase request contains LBAs that are not\r
	242	valid.\r
	243	@retval EFI_NO_MEDIA There is no media in the device.\r
	244	@retval EFI_MEDIA_CHANGED The MediaId is not for the current media.\r
	245	\r
	246	**/\r
	247	EFI_STATUS\r
	248	EFIAPI\r
	249	SdEraseBlocks (\r
	250	IN EFI_ERASE_BLOCK_PROTOCOL *This,\r
	251	IN UINT32 MediaId,\r
	252	IN EFI_LBA Lba,\r
	253	IN OUT EFI_ERASE_BLOCK_TOKEN *Token,\r
	254	IN UINTN Size\r
	255	);\r
	256	\r
48555339 FT	257	#endif\r
48555339 FT	258	\r