Skip to content

Initial revision of the SDIO Design document #11847

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Initial revision of the SDIO Design document #11847

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
194 changes: 59 additions & 135 deletions docs/design-documents/hal/sdio_api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,7 @@

### Revision history

1.0 - A brief description of this version. For example, Initial revision - Author name - Date.
**NOTE: You may also specify the Mbed OS version this revision of design document applies to.**
1.1 - Added new section - Author name - Date.
1.0 - Initial revision - Mahesh Mahadevan - 11/12/2019.

# Introduction

Expand All @@ -41,168 +39,94 @@ SDIO (Secure Digital I/O) is and extension to SD standard that provides high spe

### Requirements and assumptions

Capture the requirements for this feature to work and other assumptions made. For example, if you are assuming specific hardware capabilities, memory requirements or security assets, such as the presence of a Root of Trust infrastructure, then capture those here.

For example:

This feature requires a QuadSPI interface on the target because this feature implements a block device driver over the QuadSPI interface. It also assumes the system can provide 16K of memory for buffering.
This feature requires a SDIO interface on the target as this feature implements a block device driver over the SDIO interface.

# System architecture and high-level design

This section provides high-level information about areas or components that need changes or new development to implement this feature. Capture the high-level design goals of this feature for the target reader. Focus on what functionality it provides and not the actual implementation. For example, if you are implementing a new device driver for a communication peripheral or device, then the high-level design goals may look like:

- `Configuring the device` - The driver should provide a specific interface to configure the communication paramaters for the device.
- `Starting and stopping the device` - The driver should provide interfaces to start and stop all the communications.
- `Reading from and Writing to the device` - Read and Write interfaces should be implemented to support sending single and multiple bytes.
- `Resetting the device` - Functionality to reset the device should be provided.

Add more description to each high-level design goal if required.

**NOTE: If you already have publicly available supporting architecture documentation in the form of technology documents or other existing documents, please link to them instead of replicating the documentation.**
A SDIOBlockDevice driver is implememted to interface with the mbed-os storage framework. This driver will interact with the target
hardware using the HAL API. The HAL driver should provide the following

For each high-level design goal, provide a detailed software design in the [detailed design](#detailed-design) section, including more details on implementation.
- `Configuring the device` - The driver should implement the interfaces to intialize the device at start and deinitialize on close.
- `Reading from and Writing to the device` - Read and Write interfaces should be implemented to support blocking mode.
- `Asynchronous operations` - Non-blocking read and write interfaces
- `Read and Write status` - Interface to read the read & write status which is used during non-blocking operations.
- `Erase` - Interface to erase specified memory area
- `Get Card State` - Gets the current data status of the card
- `Get Card Info` - Gets information about a SD card

### System architecture and component interaction

Description and diagrams showing overall architecture of how the components and resources interface with one another. This section captures high-level components and their interaction and not the minute details. For example, if the new feature implements a driver and provides interfaces with application and uses memory subsystem in OS to talk to the device, the diagram may look something like:

![System architecture and component interaction](./diagram_examples/system_arch_example.jpg)

# Detailed design

This section provides a detailed design on the implementation of each of the high-level design goals. This section also captures each component or module needing changes in detail. The target audience is a developer who can read this section and start the implemention. You can capture the signature of interfaces, flow charts showing how the APIs work, data flow diagrams and so on. The headings for each detailed design section match the headings in the high-level design goals. For example, based on the example above, the headings for the detailed design sections aree `Configuring the device`, `Starting and stopping the device`, `Reading from and Writing to the device` and `Resetting the device`.

### Detailed design 1 (For example, `Configuring the device`)

**API description**

Detailed API description, such as the signature of the interface, explanation of arguments, return codes and so on. For example, if you are defining an interface for configuring the device, you may describe the API like this:

`Configure API should have following signature:
mbed_error_status_t configure(int speed, enum flow_control_t flow_control, int parity_bits);`
where:`
speed - is an integer value representing the target communication speed
flow_control - is the enum value representing the flow control to be used
parity_bits - is an integer value indicating the parity_bits to be used

And the function should return mbed_error_status_t value indicating the result of the call as below:
MBED_SUCCESS if the call is successful.
MBED_ERROR_INVALID_ARGUMENT if input values are invalid.`
MBED_ERROR_CONFIG_UNSUPPORTED if the device doesnt support the requested configuration.`

**Configuration sequence diagram**

Sequence diagrams, data flow diagrams and so on. For example, the flow chart for configure device API above may look something like:

![Configure device operation](./diagram_examples/flow_chart_example.jpg)

### Detailed design 2 (For example, `Starting and stopping the device`)

**API description**

Detailed API description, such as the signature of the interface, explanation of arguments, return codes and so on. For example, for start and stop functions exported by the driver.

**Sequence diagrams for `Starting and stopping the device`**

Sequence diagrams, data flow diagrams and so on. For example, the sequence digram for stopping the device may look something like:

![Stopping the device](./diagram_examples/sequence_diagram_example.jpg)

### Detailed design 3 (For example, `Reading from and Writing to the device`)

**API description**

Detailed API description, such as the signature of interface, explanation of arguments, return codes and so on.

**Sequence diagram for `Reading from and Writing to the device`**

Sequence diagrams, Data flow diagrams and so on.

### Detailed design N (For example, `Resetting the device`)

**API description**

Detailed API description, such as the signature of the interface, explanation of arguments, return codes and so on.

**Sequence diagram for `Resetting the device`**

Sequence diagrams, data flow diagrams and so on.

# Usage scenarios and examples

Show pseudocode or flowcharts explaining the use of the feature. For example, you may want to include some pseudocode to demonstrate how to use the read functionality with the new driver design you are proposing.

### Scenario 1 (For example, `Reading from the device`)

Mention the specific use scenarios. For example, the below examples shows how to read data from device using the new APIs.

**Scenario 1 example 1. (For example, `Reading a byte from device`**)

Mention the specific use. For example, the below example shows pseudocode for how to read a single byte data from the device using the new APIs.

```C
char in_byte = 0;
int num_bytes_read = read(&in_byte, 1);
if(num_bytes_read == 1) {
//do something
...
}
```
### API description

**Scenario 1 example 2 (For example,`Reading multiple bytes from the device`**)
The HAL driver API is as follows:

In this example, the pseudocode below shows how to read multiple bytes of data from the device using the new APIs.
### Configuring the device

```C
char in_bytes[NUM_BYTES];
int num_bytes_read = read(in_bytes, NUM_BYTES);
if(num_bytes_read == NUM_BYTES) {
//process bytes read
...
}
```
int sdio_init(void): Initializes the SD card device. Returns the status

### Scenario 2 (For example, `Writing to the device`)
int sdio_deinit(void): DeInitializes the SD card device. Returns the status

Mention other usage scenarios here. For example, you can demostrate how to write to the deviceand few examples of usage.

**Scenario 2 example 1 (For example,`Writing a byte to device`**)
### Reading from and Writing to the device

Demonstrate the specific example, for example, how to write a byte of data to device.
int sdio_readblocks(uint32_t *pData, uint32_t ReadAddr, uint32_t NumOfBlocks): Reads block(s) from a specified address
in a SD card in polling mode. pData is a pointer to the buffer where the read data will be stored, ReadAddr is an address
from where data is to be read and NumOfBlocks indicates the number of SD blocks to read. The function returns the read status.

**Scenario 2 example 2 (For example, `Writing multiple bytes to device`**)
int sdio_writeblocks(uint32_t *pData, uint32_t WriteAddr, uint32_t NumOfBlocks): Writes block(s) to a specified address in
an SD card in polling mode. pData is a pointer to the buffer that will contain the data to transmit, WriteAddr is an address
to where data is to be written and NumOfBlocks indicates the number of SD blocks to write. The function returns the write status.

Demonstrate another specific example, for example, how to write mutiple bytes of data to device.

# Tools and configuration changes
### Asynchronous operations

Explain which tools need to change and the nature of changes. For example, if the feature requires adding a new subcommand to Arm Mbed CLI, capture the details of changes and use. Capture each tool change under its own subheading as below. You can also capture new configuration values that need to be added to the Mbed .json-based configuration system. For each configuration value added, explan
the name of the configuration value, how to use it and its relation to any preprocessor defines in the implementation.
Below are asynchronous API's that will work in DMA mode.

### Tool change 1
int sdio_readblocks_async(uint32_t *pData, uint32_t ReadAddr, uint32_t NumOfBlocks): Reads block(s) from a specified address
in an SD card in non-blocking mode. This API will use DMA to transfer data. pData is a pointer to the buffer where the read
data will be stored, ReadAddr is an address from where data is to be read and NumOfBlocks indicates the number of SD blocks
to read. The function returns the read status.

For example, command-line additions and changes

### Configuration changes
int sdio_writeblocks_async(uint32_t *pData, uint32_t WriteAddr, uint32_t NumOfBlocks): Writes block(s) to a specified address
in an SD card in non-blocking mode. This API will use DMA to transfer data. pData is a pointer to the buffer that will contain
the data to transmit, WriteAddr is an address to where data is to be written and NumOfBlocks indicates the number of SD blocks
to write. The function returns the write status.

For example, configuration changes in .json files
int sdio_read_pending(void): Check if a DMA read operation is pending. The return values can be one of the following:
SD_TRANSFER_OK: No data transfer is active
SD_TRANSFER_BUSY: Data transfer is active

# Other information
int sdio_write_pending(void): Check if a DMA write operation is pending. The return values can be one of the following:
SD_TRANSFER_OK: No data transfer is active
SD_TRANSFER_BUSY: Data transfer is active

Add other relevant information you would like to capture. Add custom headings if required.

### Reusability
### Erase operation

List the components or pieces of implementation that can be reused for specific design patterns or other implementations.
int sdio_erase(uint32_t StartAddr, uint32_t EndAddr): Erases the specified memory area of the given SD card. StartAddr is the
start byte address and EndAddr is the end byte address. The function return erase status

### Deprecations

List the APIs that may be deprecated as part of this feature.
### Get Card State

### References
int sdio_get_card_state(void): Gets the current SD card data status. The return values can be one of the following:
SD_TRANSFER_OK: Card is read for data transfer
SD_TRANSFER_ERROR: Card is not ready

Capture information, such as specifications, other design documentation and other implementations URLs.

### Custom headings
### Get Card Info
void sdio_get_card_info(SDIO_Cardinfo_t *CardInfo): Get information about specific SD card. CardInfo is a pointer to
HAL SD_CardInfo structure

Add custom headings. For example, you can put security effects of this feature under the heading `Security effects`.
typedef struct {
uint32_t CardType; /* Specifies the card Type */
uint32_t CardVersion; /* Specifies the card version */
uint32_t Class; /* Specifies the class of the card class */
uint32_t RelCardAdd; /* Specifies the Relative Card Address */
uint32_t BlockNbr; /* Specifies the Card Capacity in blocks */
uint32_t BlockSize; /* Specifies one block size in bytes */
uint32_t LogBlockNbr; /* Specifies the Card logical Capacity in blocks */
uint32_t LogBlockSize; /* Specifies logical block size in bytes */
} SDIO_Cardinfo_t;