1 /* 2 * Copyright (c) 2025 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup ScsiPeripheralDDK 18 * @{ 19 * 20 * @brief Provide ScsiPeripheral DDK interface, including initializing DDK, releasing DDK, opening devices, reading\n 21 * and writing devices, etc. 22 * @since 18 23 */ 24 25 /** 26 * @file scsi_peripheral_api.h 27 * 28 * @brief Declares the ScsiPeripheral DDK APIs. 29 * 30 * @kit DriverDevelopmentKit 31 * @library libscsi.z.so 32 * @syscap SystemCapability.Driver.SCSI.Extension 33 * @since 18 34 */ 35 36 #ifndef SCSI_PERIPHERAL_API_H 37 #define SCSI_PERIPHERAL_API_H 38 39 #include <stdint.h> 40 #include "scsi_peripheral_types.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif /* __cplusplus */ 45 46 /** 47 * @brief Initializes the ScsiPeripheral DDK. 48 * 49 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 50 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 51 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 52 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk init error. 53 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 54 * @since 18 55 */ 56 int32_t OH_ScsiPeripheral_Init(void); 57 58 /** 59 * @brief Releases the ScsiPeripheral DDK. 60 * 61 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 62 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 63 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 64 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 65 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 66 * @since 18 67 */ 68 int32_t OH_ScsiPeripheral_Release(void); 69 70 /** 71 * @brief Open SCSI device by deviceId. 72 * 73 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 74 * @param deviceId ID of the device to be operated. 75 * @param interfaceIndex Interface index, which corresponds to interface which supports USB Protocol UAS. 76 * @param dev Device handle. 77 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 78 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 79 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 80 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null. 81 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 82 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 83 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 84 * {@link SCSIPERIPHERAL_DDK_DEVICE_NOT_FOUND} device not found by deviceId. 85 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 86 * @since 18 87 */ 88 int32_t OH_ScsiPeripheral_Open(uint64_t deviceId, uint8_t interfaceIndex, ScsiPeripheral_Device **dev); 89 90 /** 91 * @brief Close SCSI device. 92 * 93 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 94 * @param dev Device handle. 95 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 96 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 97 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 98 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null. 99 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 100 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 101 * @since 18 102 */ 103 int32_t OH_ScsiPeripheral_Close(ScsiPeripheral_Device **dev); 104 105 /** 106 * @brief Check if the logical unit is ready. 107 * 108 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 109 * @param dev Device handle. 110 * @param request Test unit ready request information. 111 * @param response The response parameters. 112 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 113 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 114 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 115 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or response is null. 116 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 117 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 118 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 119 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 120 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 121 * @since 18 122 */ 123 int32_t OH_ScsiPeripheral_TestUnitReady(ScsiPeripheral_Device *dev, ScsiPeripheral_TestUnitReadyRequest *request, 124 ScsiPeripheral_Response *response); 125 126 /** 127 * @brief Get the information regarding the logical unit and SCSI target device. 128 * 129 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 130 * @param dev Device handle. 131 * @param request Inquiry request information. 132 * @param inquiryInfo The data of inquiry command. 133 * @param response The response parameters. 134 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 135 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 136 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 137 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or inquiryInfo is null or\n 138 * inquiryInfo->data is null or response is null. 139 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 140 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 141 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 142 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 143 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 144 * @since 18 145 */ 146 int32_t OH_ScsiPeripheral_Inquiry(ScsiPeripheral_Device *dev, ScsiPeripheral_InquiryRequest *request, 147 ScsiPeripheral_InquiryInfo *inquiryInfo, ScsiPeripheral_Response *response); 148 149 /** 150 * @brief Get the device capacity. 151 * 152 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 153 * @param dev Device handle. 154 * @param request ReadCapacity request information. 155 * @param capacityInfo The data of read capacity command. 156 * @param response The response parameters. 157 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 158 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 159 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 160 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or capacityInfo is null or\n 161 * response is null. 162 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 163 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 164 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 165 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 166 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 167 * @since 18 168 */ 169 int32_t OH_ScsiPeripheral_ReadCapacity10(ScsiPeripheral_Device *dev, ScsiPeripheral_ReadCapacityRequest *request, 170 ScsiPeripheral_CapacityInfo *capacityInfo, ScsiPeripheral_Response *response); 171 172 /** 173 * @brief Get the sense data. 174 * 175 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 176 * @param dev Device handle. 177 * @param request RequestSense request information. 178 * @param response The response parameters. 179 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 180 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 181 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 182 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or response is null. 183 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 184 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 185 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 186 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 187 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 188 * @since 18 189 */ 190 int32_t OH_ScsiPeripheral_RequestSense(ScsiPeripheral_Device *dev, ScsiPeripheral_RequestSenseRequest *request, 191 ScsiPeripheral_Response *response); 192 193 /** 194 * @brief Read from the specified logical block(s). 195 * 196 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 197 * @param dev Device handle. 198 * @param request The request parameters. 199 * @param response The response parameters. 200 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 201 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 202 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 203 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or request->data is null or\n 204 * response is null. 205 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 206 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 207 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 208 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 209 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 210 * @since 18 211 */ 212 int32_t OH_ScsiPeripheral_Read10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, 213 ScsiPeripheral_Response *response); 214 215 /** 216 * @brief Write data to the specified logical block(s). 217 * 218 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 219 * @param dev Device handle. 220 * @param request The request parameters. 221 * @param response The response parameters. 222 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 223 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 224 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 225 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or request->data is null or\n 226 * response is null. 227 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 228 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 229 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 230 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 231 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 232 * @since 18 233 */ 234 int32_t OH_ScsiPeripheral_Write10(ScsiPeripheral_Device *dev, ScsiPeripheral_IORequest *request, 235 ScsiPeripheral_Response *response); 236 237 /** 238 * @brief Verify the specified logical block(s) on the medium. 239 * 240 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 241 * @param dev Device handle. 242 * @param request Verify request information. 243 * @param response The response parameters. 244 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 245 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 246 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 247 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or response is null. 248 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 249 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 250 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 251 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 252 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 253 * @since 18 254 */ 255 int32_t OH_ScsiPeripheral_Verify10(ScsiPeripheral_Device *dev, ScsiPeripheral_VerifyRequest *request, 256 ScsiPeripheral_Response *response); 257 258 /** 259 * @brief Send SCSI command that specified by CDB. 260 * 261 * @permission ohos.permission.ACCESS_DDK_SCSI_PERIPHERAL 262 * @param dev Device handle. 263 * @param request The request parameters. 264 * @param response The response parameters. 265 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 266 * {@link SCSIPERIPHERAL_DDK_NO_PERM} permission check failed. 267 * {@link SCSIPERIPHERAL_DDK_INIT_ERROR} the ddk not init. 268 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or request is null or request->data is null or\n 269 * request->cdbLength is 0 or response is null. 270 * {@link SCSIPERIPHERAL_DDK_SERVICE_ERROR} communication with ddk service failed. 271 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 272 * {@link SCSIPERIPHERAL_DDK_IO_ERROR} i/o operation error. 273 * {@link SCSIPERIPHERAL_DDK_TIMEOUT} transmission timeout. 274 * {@link SCSIPERIPHERAL_DDK_INVALID_OPERATION} this operation is not supported. 275 * @since 18 276 */ 277 int32_t OH_ScsiPeripheral_SendRequestByCdb(ScsiPeripheral_Device *dev, ScsiPeripheral_Request *request, 278 ScsiPeripheral_Response *response); 279 280 /** 281 * @brief Creates a buffer. To avoid resource leakage, destroy a buffer by calling\n 282 * <b>OH_ScsiPeripheral_DestroyDeviceMemMap</b> after use. 283 * 284 * @param dev Device handle. 285 * @param size Buffer size. 286 * @param devMmap Data memory map, through which the created buffer is returned to the caller. 287 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 288 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} dev is null or devMmap is null. 289 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 290 * @since 18 291 */ 292 int32_t OH_ScsiPeripheral_CreateDeviceMemMap(ScsiPeripheral_Device *dev, size_t size, 293 ScsiPeripheral_DeviceMemMap **devMmap); 294 295 /** 296 * @brief Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. 297 * 298 * @param devMmap Device memory map created by calling <b>OH_ScsiPeripheral_CreateDeviceMemMap</b>. 299 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 300 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} devMmap is null. 301 * {@link SCSIPERIPHERAL_DDK_MEMORY_ERROR} memory data operation failed. 302 * @since 18 303 */ 304 int32_t OH_ScsiPeripheral_DestroyDeviceMemMap(ScsiPeripheral_DeviceMemMap *devMmap); 305 306 /** 307 * @brief Parse the basic sense data of Information、Command-specific information、Sense key specific. 308 * 309 * @param senseData Sense data. 310 * @param senseDataLen The length of sense data. 311 * @param senseInfo Basic sense data. 312 * @return {@link SCSIPERIPHERAL_DDK_SUCCESS} the operation is successful. 313 * {@link SCSIPERIPHERAL_DDK_INVALID_PARAMETER} senseData is null or senseInfo is null or\n 314 * senseData format is not Descriptor/Fixed format or\n 315 * senseDataLen is smaller than SCSIPERIPHERAL_MIN_DESCRIPTOR_FORMAT_SENSE or\n 316 * senseDataLen is smaller than SCSIPERIPHERAL_MIN_FIXED_FORMAT_SENSE. 317 * @since 18 318 */ 319 int32_t OH_ScsiPeripheral_ParseBasicSenseInfo(uint8_t *senseData, uint8_t senseDataLen, 320 ScsiPeripheral_BasicSenseInfo *senseInfo); 321 #ifdef __cplusplus 322 } 323 #endif /* __cplusplus */ 324 #endif // SCSI_PERIPHERAL_API_H 325 /** @} */ 326