Step 5: Review the Application Code

Open file app_tone_textfile_sdcard.h. This file defines application states, data, and APIs.

Application states corresponding to the state machine, described in the Overview section of this lab, are as follows. Note the newly added states highlighted in the red box.

The application data structure is shown in the accompanying image.

• The variable state and CODEC are retained from audio_player_lab1. They hold the state of application and codec-related variables respectively.
• audio_player_lab1 had the audio data saved in a global buffer, whereas audio_player_lab2 will read ASCII audio text data from a file saved in the SD card. This ASCII data needs to be parsed. The variable textParser holds the ASCII text data to be parsed (see APP_TONE_TEXTFILE_AUDIO_DATA_PARSER in the following figure).
• fileHandle holds the handle to a file opened by using the File System API call SYS_FS_FileOpen.
• fileSize holds the size of the opened file.
• currentFilePosition holds the current file position.
• buffer holds the ASCII data read from the tone.txt file. The buffer serves as an input to the audio data parser routine. It converts the comma-separated ASCII audio values to binary integer values.
• nElements holds the number of ASCII values present in the buffer that need to be parsed.
  

• The CODEC data structure will remain the same. It is included here for completeness.
  

APIs for initialization, task state machine, and buffer completion events are declared.

Open file app_tone_textfile_sdcard.c. This file contains the application state machine and implements the APIs.

The implementation of function APP_TONE_TEXTFILE_SDCARD_Initialize sets up the default state of APP_TONE_TEXTFILE_SDCARD_Tasks and initializes the variables for the CODEC driver, along with other variables.

The function APP_TONE_TEXTFILE_SDCARD_Tasks implements the task’s state machine as shown in the figure in the Overview section of this lab.

As with audio_player_lab1, it starts in APP_TONE_TEXTFILE_SDCARD_STATE_CODEC_OPEN state and remains in it until it opens the CODEC driver and gets a valid driver handle.

The state APP_TONE_TEXTFILE_SDCARD_STATE_CODEC_SET_BUFFER_HANDLER registers a buffer event handler with the CODEC driver.

The state APP_TONE_TEXTFILE_SDCARD_STATE_CARD_MOUNT mounts the FAT file system to the SD card.

After the file system is successfully mounted, the state machine enters APP_TONE_TEXTFILE_SDCARD_STATE_CARD_CURRENT_DRIVE_SET state where it sets the current drive of the file system to the specified path and then opens the tone.txt audio file.

In the APP_TONE_TEXTFILE_SDCARD_STATE_READ_FILE_SIZE, the size of the opened file (tone.txt) is read.

The state APP_TONE_TEXTFILE_SDCARD_STATE_CARD_READ reads the ASCII audio data contained in the tone.txt file and passes the read buffer to the APP_TONE_TEXTFILE_SDCARD_Parse_Audio_Text_Data routine, which converts it to binary data and saves it in the buffer pointed by the CODEC variable.

The entire tone.txt file is read and converted in one shot, and the audio data buffer appToneTextFileSdcardToneBuffer is updated.

In state APP_TONE_TEXTFILE_SDCARD_STATE_CODEC_ADD_BUFFER, the application submits audio data buffers to the driver queue and enters into a waiting state (APP_TONE_TEXTFILE_SDCARD_STATE_CODEC_WAIT_FOR_BUFFER_COMPLETE) for the last submitted buffer to complete. The number of buffers queued is equal to queue_size-1 (i.e., two buffers).

The Direct Memory Access (DMA) transfers the last buffer and the CODEC calls the event handler when the buffer transmission is completed.
In the event handler APP_TONE_TEXTFILE_SDCARD_BufferEventHandler, the state of the task is changed from waiting to complete.

A new buffer is submitted from the state APP_TONE_TEXTFILE_SDCARD_STATE_CODEC_BUFFER_COMPLETE and the state machine goes to the waiting state again. The cycle of waiting <-> complete state continues.