# sd_card

Library for communicating with SD memory cards

Author | Matthew Schinkel - borntechi.com, copyright © 2009..2022, all rights reserved.
Adapted-by | Rob Jansen + Matthew Schinkel
Compiler | 2.5r9

Description

    this library provides functions for SD memory cards.

Sources

    SanDisk Secure Digital Card - http://www.cs.ucr.edu/~amitra/sdcard/ProdManualSDCardv1.9.pdf
    How to use MMC/SDC - http://forums.parallax.com/forums/attach.aspx?a=32012
    http://www.rjhcoding.com/avrc-sd-interface-3.php

Notes

    SD card SPI mode is 1,1

Dependencies

- print
- large_array_6

## Summary

### Global variables/contants

- `const byte SD_COMMAND_CRC_ERROR = 9`
- `var dword sd_error_count = 0`
- `const bit SD_STANDARD_CAPACITY = 1`
- `const byte SD_CRC_ERROR = 8`
- `const byte SD_CLR_WRITE_PROT = 29`
- `const byte SD_TIMED_OUT = 3`
- `var word sd_error_details = 0`
- `const SD_CARD = 1`
- `const byte SD_SEND_IF_COND = 8`
- `const byte SD_ERASE_WR_BLK_END = 33`
- `const DATA_MEDIA = SD_CARD`
- `const byte SD_SEND_WRITE_PROT = 30`
- `const word SD_BYTE_PER_SECTOR = 512`
- `const byte SD_STOP_TRANSMISSION = 12`
- `const byte SD_WRITE_MULTIPLE_BLOCK = 25`
- `const byte SD_SEND_STATUS = 13`
- `const byte SD_INIT_FAILURE = 2`
- `var dword sd_number_of_sectors`
- `const byte SD_PROGRAM_CSD = 27`
- `var byte sd_max_retries = 3`
- `const dword LARGE_ARRAY_6_SIZE = 512`
- `const byte SD_DEVICE_NOT_FOUND = 0`
- `const byte SD_SEND_CSD = 9`
- `const byte SD_CRC_ON_OFF = 59`
- `var dword sd_success_count = 0`
- `const byte SD_SEND_NUM_WR_BLOCKS = 22`
- `var word sd_sector_count = 0`
- `const byte SD_COMMAND_TIME_OUT = 4`
- `const byte SD_READ_SINGLE_BLOCK = 17`
- `const byte SD_SET_CLR_CARD_DETECT = 42`
- `const byte SD_IN_IDLE_STATE = 0`
- `const byte SD_ERASE_WR_BLK_START = 32`
- `var bit sd_card_type = 0`
- `const bit SD_HIGH_CAPACITY = 0`
- `const byte SD_GO_IDLE_STATE = 0`
- `const byte SD_SET_BLOCKLEN = 16`
- `const byte SD_READ_ERROR = 6`
- `var byte sd_retry_count = 0`
- `const byte SD_SD_APP_OP_COND = 41`
- `const byte SD_WRITE_ERROR = 7`
- `const byte SD_ERASE_RESET = 1`
- `const dword LARGE_ARRAY_6_VARIABLE_SIZE = 1`
- `const byte SD_COM_CRC_ERROR = 3`
- `const byte SD_SEND_SCR = 51`
- `var bit sd_has_init = 0`
- `const byte SD_PARAMETER_ERROR = 6`
- `const byte SD_READ_MULTIPLE_BLOCK = 18`
- `const PATA_HARD_DISK = 0`
- `const byte SD_DATA_CRC_ERROR = 10`
- `const byte SD_SEND_OP_COND = 1`
- `const byte SD_READ = 0`
- `const byte SD_ILLEGAL_COMMAND = 2`
- `const byte SD_COMMAND_NOT_SUPPORTED = 5`
- `const byte SD_WRITE = 1`
- `var dword sd_sector_select`
- `const byte SD_WRITE_BLOCK = 24`
- `const byte SD_GEN_CMD = 56`
- `const byte SD_SEND_CID = 10`
- `const byte SD_APP_CMD = 55`
- `const byte SD_SD_STATUS = 13`
- `const byte SD_ERASE = 38`
- `const byte SD_ADDRESS_ERROR = 5`
- `var bit sd_has_error = 0`
- `const byte SD_SET_WR_BLK_ERASE_COUNT = 23`
- `const byte SD_TYPE_NOT_SUPPORTED = 1`
- `const byte SD_READ_OCR = 58`
- `const byte SD_ERASE_SEQUENCE_ERROR = 4`
- `var word sd_byte_count = 0`
- `const byte SD_SET_WRITE_PROT = 28`

### Procedures

- `sd_read_sector_address(dword in address)`
- `sd_write_sector()`
- `sd_stop_read()`
- `sd_error'put(word in error)`
- `sd_write_pulse(byte in count1)`
- `sd_write_sector_with_callback(word in chunk_size)`
- `sd_stop_write()`
- `sd_seperator()`
- `sd_print_response(volatile byte out device,byte in response)`
- `sd_check_crc_errors()`
- `sd_print_enhanced_statistics()`
- `send_command(byte in command,dword in data, byte out response)`
- `sd_enable()`
- `sd_toggle()`
- `sd_reset_error_state()`
- `sd_print_error(volatile byte out device)`
- `sd_set_idle()`
- `sd_print_sector_hex(volatile byte out device,word in bytes_per_line,dword in address)`
- `sd_write_sector_address(dword in address)`
- `sd_retry_operation(dword in sector_address, byte in operation_type)`
- `sd_read_pulse_byte(word in count1)`
- `sd_read_sector_with_callback(word in chunk_size)`
- `sd_start_write(dword in address)`
- `sd_disable()`
- `sd_write_to_sector_end(byte in input_byte)`
- `sd_init()`
- `sd_print_sector(volatile byte out device, dword in address)`
- `sd_write_pulse_byte(word in count1)`
- `sd_read_sector()`
- `sd_start_read(dword in address)`
- `sd_data_byte'put(byte in data_byte)`

Private

- `_sd_read_512()`
- `_sd_write_512()`
- `_sd_read_512_crc()`
- `_sd_write_512_crc()`

### Functions

- `sd_error'get() return word`
- `sd_read_write_next_ready(byte in read_write) return byte`
- `sd_data_byte'get() return byte`
- `sd_ready() return byte`
- `sd_is_inserted() return bit`

## API details

### Global variables/contants

- `const byte SD_COMMAND_CRC_ERROR = 9`

  No documentation found

- `var dword sd_error_count = 0`

  No documentation found

- `const bit SD_STANDARD_CAPACITY = 1`

  No documentation found

- `const byte SD_CRC_ERROR = 8`

  No documentation found

- `const byte SD_CLR_WRITE_PROT = 29`

  No documentation found

- `const byte SD_TIMED_OUT = 3`

  No documentation found

- `var word sd_error_details = 0`

  No documentation found

- `const SD_CARD = 1`

  No documentation found

- `const byte SD_SEND_IF_COND = 8`

      for SDHC only

- `const byte SD_ERASE_WR_BLK_END = 33`

  No documentation found

- `const DATA_MEDIA = SD_CARD`

  No documentation found

- `const byte SD_SEND_WRITE_PROT = 30`

  No documentation found

- `const word SD_BYTE_PER_SECTOR = 512`

  No documentation found

- `const byte SD_STOP_TRANSMISSION = 12`

  No documentation found

- `const byte SD_WRITE_MULTIPLE_BLOCK = 25`

  No documentation found

- `const byte SD_SEND_STATUS = 13`

  No documentation found

- `const byte SD_INIT_FAILURE = 2`

  No documentation found

- `var dword sd_number_of_sectors`

      number of sectors variable

- `const byte SD_PROGRAM_CSD = 27`

  No documentation found

- `var byte sd_max_retries = 3`

      =============================================================================
      Enhanced Error Handling Variables
      =============================================================================

- `const dword LARGE_ARRAY_6_SIZE = 512`

      Define sector buffer for SD card operations
      Use Large Array to set up the sector buffer (512 bytes)

- `const byte SD_DEVICE_NOT_FOUND = 0`

  No documentation found

- `const byte SD_SEND_CSD = 9`

      sd sends "Card Specific Data" standard or high capacity

- `const byte SD_CRC_ON_OFF = 59`

      default is off

- `var dword sd_success_count = 0`

  No documentation found

- `const byte SD_SEND_NUM_WR_BLOCKS = 22`

  No documentation found

- `var word sd_sector_count = 0`

  No documentation found

- `const byte SD_COMMAND_TIME_OUT = 4`

  No documentation found

- `const byte SD_READ_SINGLE_BLOCK = 17`

  No documentation found

- `const byte SD_SET_CLR_CARD_DETECT = 42`

  No documentation found

- `const byte SD_IN_IDLE_STATE = 0`

      R1 RESPONSE BITS

- `const byte SD_ERASE_WR_BLK_START = 32`

      Erase Commands

- `var bit sd_card_type = 0`

      misc variables

- `const bit SD_HIGH_CAPACITY = 0`

  No documentation found

- `const byte SD_GO_IDLE_STATE = 0`

      Basic Commands

- `const byte SD_SET_BLOCKLEN = 16`

      Read Commands

- `const byte SD_READ_ERROR = 6`

  No documentation found

- `var byte sd_retry_count = 0`

  No documentation found

- `const byte SD_SD_APP_OP_COND = 41`

  No documentation found

- `const byte SD_WRITE_ERROR = 7`

  No documentation found

- `const byte SD_ERASE_RESET = 1`

  No documentation found

- `const dword LARGE_ARRAY_6_VARIABLE_SIZE = 1`

      choose bytes size of variables

- `const byte SD_COM_CRC_ERROR = 3`

  No documentation found

- `const byte SD_SEND_SCR = 51`

  No documentation found

- `var bit sd_has_init = 0`

  No documentation found

- `const byte SD_PARAMETER_ERROR = 6`

  No documentation found

- `const byte SD_READ_MULTIPLE_BLOCK = 18`

  No documentation found

- `const PATA_HARD_DISK = 0`

      constants for fat32 library

- `const byte SD_DATA_CRC_ERROR = 10`

  No documentation found

- `const byte SD_SEND_OP_COND = 1`

  No documentation found

- `const byte SD_READ = 0`

      Read/write constants

- `const byte SD_ILLEGAL_COMMAND = 2`

  No documentation found

- `const byte SD_COMMAND_NOT_SUPPORTED = 5`

  No documentation found

- `const byte SD_WRITE = 1`

  No documentation found

- `var dword sd_sector_select`

  No documentation found

- `const byte SD_WRITE_BLOCK = 24`

      Write Commands

- `const byte SD_GEN_CMD = 56`

  No documentation found

- `const byte SD_SEND_CID = 10`

  No documentation found

- `const byte SD_APP_CMD = 55`

      Application Specific Commands

- `const byte SD_SD_STATUS = 13`

      application specific command, must write command 55 first

- `const byte SD_ERASE = 38`

  No documentation found

- `const byte SD_ADDRESS_ERROR = 5`

  No documentation found

- `var bit sd_has_error = 0`

      error codes
      if any are added, they should be added to sd_print_error()

- `const byte SD_SET_WR_BLK_ERASE_COUNT = 23`

  No documentation found

- `const byte SD_TYPE_NOT_SUPPORTED = 1`

  No documentation found

- `const byte SD_READ_OCR = 58`

      Other Commands

- `const byte SD_ERASE_SEQUENCE_ERROR = 4`

  No documentation found

- `var word sd_byte_count = 0`

      counters

- `const byte SD_SET_WRITE_PROT = 28`

      Write Protection Commands

### Procedures

- `sd_read_sector_address(dword in address)`

      read one entire sector at address

- `sd_write_sector()`

      write one entire sector

- `sd_stop_read()`

      tell sd card you are finished reading
      needed to be the same as other mass media libs

- `sd_error'put(word in error)`

      set sd_card error

- `sd_write_pulse(byte in count1)`

  No documentation found

- `sd_write_sector_with_callback(word in chunk_size)`

      write one entire sector with callback to storage_write_callback()
      for direct reading with spi_master. Make sure you call spi_master
      chunk_size times in your storage_write_callback().

- `sd_stop_write()`

      tell sd card you are finished writing

- `sd_seperator()`

      Print separator line

- `sd_print_response(volatile byte out device,byte in response)`

      Print R1 Response

- `sd_check_crc_errors()`

      Check for errors and print detailed error information

- `sd_print_enhanced_statistics()`

      Print enhanced error handling statistics

- `send_command(byte in command,dword in data, byte out response)`

      send a command to the sd card (commands with 1 response only)

- `sd_enable()`

      Enable the sd card

- `sd_toggle()`

      Disable then enable the sd card

- `sd_reset_error_state()`

      Reset error state for retry

- `sd_print_error(volatile byte out device)`

      Report sd card error (does NOT reset error status)

- `sd_set_idle()`

      set the sd card to idle state

- `sd_print_sector_hex(volatile byte out device,word in bytes_per_line,dword in address)`

      print a sector to an output device in ascii hex

- `sd_write_sector_address(dword in address)`

      write one entire sector at address

- `sd_retry_operation(dword in sector_address, byte in operation_type)`

      Simple retry mechanism for operations

- `sd_read_pulse_byte(word in count1)`

      send a read pulse to the sd card, go 1 bytes forward in current sector.

- `sd_read_sector_with_callback(word in chunk_size)`

  No documentation found

- `sd_start_write(dword in address)`

      tell sd card you will be writing data to a specified sector
      must write 1 sector at a time, SD_BYTE_PER_SECTOR bytes
      do not interupt write process by switching to another spi component

- `sd_disable()`

      Disable the sd card

- `sd_write_to_sector_end(byte in input_byte)`

      write till sector is finished with input byte
      data does not actually get written till you get to the end of the sector

- `sd_init()`

      Enhanced SD card initialization with improved error handling and reporting

- `sd_print_sector(volatile byte out device, dword in address)`

      print a sector to an output device

- `sd_write_pulse_byte(word in count1)`

  No documentation found

- `sd_read_sector()`

      read one entire sector

- `sd_start_read(dword in address)`

      tell sd card you will be reading data from a specified sector
      do not interupt read process by switching to another spi component

- `sd_data_byte'put(byte in data_byte)`

      write 1 byte to the sd card (pseudo var)

Private

- `_sd_read_512()`

      Extra speed read procedure

- `_sd_write_512()`

      Extra speed write procedure

- `_sd_read_512_crc()`

  No documentation found

- `_sd_write_512_crc()`

  No documentation found

### Functions

- `sd_error'get() return word`

      read sd card error (resets error status)

- `sd_read_write_next_ready(byte in read_write) return byte`

  No documentation found

- `sd_data_byte'get() return byte`

      read 1 bytes from the sd card (pseudo var)

- `sd_ready() return byte`

      check if the sd card is ready after last command.
      returns 1 if ready, 0 if not ready.

- `sd_is_inserted() return bit`

      Check if SD card exists

## Related samples

Here are the list of samples which use this library:

16f18857 | 16f18857_glcd_ili9341_fat32_sd_card.jal
18f26j50 | 18f26j50_sd_card.jal
18f26j50 | 18f26j50_fat32_sd_card.jal
18f27j53 | 18f27j53_sd_card_minix_demo.jal
18f27j53 | 18f27j53_sd_card_minix_read.jal
18f27j53 | 18f27j53_sd_card_minix_readi.jal
18f452 | 18f452_fat32_small_sd_card.jal
18f452 | 18f452_sd_card.jal
18f4525 | 18f4525_fat32_sd_card.jal
18f4525 | 18f4525_mp3_decoder_vs1053b_sd_card.jal
18f4525 | 18f4525_sd_card.jal
18f4525 | 18f4525_fat32_small_sd_card.jal
18f4550 | 18f4550_sd_card.jal
18f4550 | 18f4550_fat32_small_sd_card.jal
18f4620 | 18f4620_mp3_decoder_vs1053b_sd_card.jal
18f4620 | 18f4620_sd_card.jal
18f4620 | 18f4620_fat32_small_sd_card.jal
18f4620 | 18f4620_fat32_sd_card.jal
18f67j50 | 18f67j50_sd_card.jal
18f67j50 | 18f67j50_mp3_decoder_vs1053b_sd_card.jal
18f67j50 | 18f67j50_sd_card_crc.jal
18f67j50 | 18f67j50_usb_msd_sd_card.jal
18f67j50 | 18f67j50_fat32_usb_msd_sd_card.jal
18f67j50 | 18f67j50_fat32_sd_card.jal
18f67j50 | 18f67j50_fat32_small_sd_card.jal
18f67j60 | 18f67j60_sd_card.jal
18f67j60 | 18f67j60_fat32_sd_card.jal