DOCA Storage GGA Offload SBC Generator Application Guide

The doca_storage_gga_offload_sbc_generator application provides a utility for generating storage-ready binary content files for use with DOCA storage target applications in the GGA offload use case.

This tool processes a single input file, breaks it into chunks, compresses the data, generates parity, and outputs three .sbc files suitable for use by the GGA Offload pipeline.

The application performs the following operations in sequence:

1. Load input data from disk.

2. Compress data using the LZ4 compression algorithm.

3. Generate parity data via error correction coding (2:1 ratio).

4. Write the resulting binary output files to disk, organized into three partitions.

The doca_storage_gga_offload_sbc_generator is not performance-critical and follows a straightforward, linear processing flow. The application comprises the following key steps:

1. Load the source file from disk.

2. Divide the file content into chunks.

3. Compress each chunk using the LZ4 library.

   • If a chunk is not compressible enough (i.e., it cannot be reduced by at least the size of the metadata header and trailer), the application reports an error and exits.

4. Wrap each compressed chunk with a metadata header and trailer to form a storage block.

   • This metadata enables the GGA Offload application to correctly reconstruct decompression tasks.

5. Generate EC (Erasure Coding) parity for each storage block.

   • The parity is generated at a 2:1 ratio: for every 2 bytes of data, 1 byte of parity is produced. This allows for 50% of the data to be lost and still be recoverable using the parity.

6. Split the content into three logical partitions:

   • Data 1 and Data 2 are currently identical copies.

   • Parity contains duplicated parity data.

     Note

     This replication strategy is for simplicity and does not reflect a realistic storage deployment.

7. Write each partition to disk, including high-level metadata such as:

   • Storage block size

   • Number of storage blocks

This application leverages the following DOCA libraries:

• DOCA Erasure Coding

This application is compiled as part of the set of storage applications. For compilation instructions, refer to the DOCA Storage page.

Application Execution

• Application usage instructions:

  Copy

  Copied!

              
  
              
  Usage: doca_storage_gga_offload_sbc_generator [DOCA Flags] [Program Flags]
   
  DOCA Flags:
    -h, --help                        Print a help synopsis
    -v, --version                     Print program version information
    -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
    --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
   
  Program Flags:
    -d, --device                      Device identifier
    --original-input-data             File containing the original data that is represented by the storage
    --block-size                      Size of each block. Default: 4096
    --matrix-type                     Type of matrix to use. One of: cauchy, vandermonde Default: vandermonde
    --data-1                          First half of the data in storage
    --data-2                          Second half of the data in storage
    --data-p                          Parity data (used to perform recovery flow)
          

  Info

  This usage printout can be printed to the command line using the -h (or --help) options:

  Copy

  Copied!

              
  
              
  ./doca_storage_gga_offload_sbc_generator -h
          

  For additional information, refer to section "Command-line Flags".

• CLI example for running the application on the BlueField:

  Copy

  Copied!

              
  
              
  ./doca_storage_gga_offload_sbc_generator -d 03:00.0 --original-input-data original_data.txt --block-size 4096 --data-1 data_1.sbc --data-2 data_2.sbc --data-p data_p.sbc
          

  Note

  The device PCIe address (03:00.0) should match the addresses of the desired PCIe device.

Command-line Flags

Troubleshooting

Refer to the NVIDIA BlueField Platform Software Troubleshooting Guide for any issue encountered with the installation or execution of the DOCA applications.

General Application Flow

The high-level flow of the doca_storage_gga_offload_sbc_generator application proceeds as follows:

1. The high level application flow is as follows:

   Copy

   Copied!

               
   
               
   auto const cfg = parse_cli_args(argc, argv);
   gga_offload_sbc_gen_app app{cfg.device_id, cfg.ec_matrix_type, cfg.block_size};
           

2. Load input data from disk:

   Copy

   Copied!

               
   
               
   auto input_data = storage::load_file_bytes(cfg.original_data_file_name);
           

3. Pad input data to ensure it aligns with the block size:

   Copy

   Copied!

               
   
               
   pad_input_to_multiple_of_block_size(input_data, cfg.block_size);
           

4. Transform the data (compression, metadata wrapping, parity generation):

   Copy

   Copied!

               
   
               
   app.generate_binary_content(input_data);
           

5. Write the output partitions to disk:

   Copy

   Copied!

               
   
               
   storage::write_binary_content_to_file(
       cfg.data_1_file_name,
       storage::binary_content{cfg.block_size, results.block_count, std::move(results.data_1_content)}
   );
    
   storage::write_binary_content_to_file(
       cfg.data_2_file_name,
       storage::binary_content{cfg.block_size, results.block_count, std::move(results.data_2_content)}
   );
    
   storage::write_binary_content_to_file(
       cfg.data_p_file_name,
       storage::binary_content{cfg.block_size, results.block_count, std::move(results.data_p_content)}
   );
           

Transform Process

1. Compress the chunk using LZ4:

   Copy

   Copied!

               
   
               
   auto const compresed_size =
       m_lz4_ctx.compress(
           input_data.data() + (ii * m_block_size),
           m_block_size,
           m_compressed_bytes_buffer.data() + metadata_header_size,
           m_compressed_bytes_buffer.size() - metadata_overhead_size
       );
           

2. Create and insert the metadata header:

   Copy

   Copied!

               
   
               
   storage::compressed_block_header const hdr{
       htobe32(m_block_size),
       htobe32(compresed_size),
   };
    
   std::copy(
       reinterpret_cast<char const *>(&hdr),
       reinterpret_cast<char const *>(&hdr) + sizeof(hdr),
       m_compressed_bytes_buffer.data()
   );
           

3. Set input buffer for parity generation and reset the output buffer:

   Copy

   Copied!

               
   
               
   doca_buf_set_data(m_input_buf, m_compressed_bytes_buffer.data(), m_block_size);
   doca_buf_reset_data_len(m_output_buf);
           

4. Submit the parity generation task to the DOCA EC engine:

   Copy

   Copied!

               
   
               
   doca_task_submit(doca_ec_task_create_as_task(m_ec_task));
           

• /opt/mellanox/doca/applications/storage/