What kind of api does a sata hard drive expose?

Question

I understand that the linux kernel uses a driver to communicate with the hard disk device and that there is firmware code on the device to service the driver's requests. My questions are:

1. what kind of functionality (i.e. api) does the firmware expose? For example, does it only expose an address space that the kernel manages, or is there some code in the linux kernel that deals with some of the physics related to the hard drive (i.e. data layout on track/sector/platter etc...)

2. Does the kernel schedule the disk's head movement, or is it the firmware?

3. Is there a standard spec for the apis exposed by hard disk devices?

Answer 1

I understand that the linux kernel uses a driver to communicate with the hard disk device

That's true for all peripherals.

there is firmware code on the device to service the driver's requests

Modern HDDs (since the advent of IDE) have an integrated disk controller.
"Firmware" by itself isn't going to do anything, and is an ambiguous description. I.E. what is executing this "firmware"?

1. what kind of functionality (i.e. api) does the firmware expose? For example, does it only expose an address space that the kernel manages, or is there some code in the linux kernel that deals with some of the physics related to the hard drive (i.e. data layout on track/sector/platter etc...)

SATA drives use the ATA Packet Interface, ATAPI.

The old SMD and ST506 drive interfaces used cylinder, head, and sector (aka CHS) addressing. Disk controllers for such drives typically kept a similar interface on the host side, so the operating system was obligated to be aware of the drive (physical) geometry. OSes would try to optimize performance by aligning partitions to cylinders, and minimize seek/access time by ordering requests by cylinder address.

Although the disk controller typically required CHS addressing, the higher layers of an OS would use a sequential logical sector address. Conversion between a logical sector address to cylinder, head, & sector address is straightforward so long as the drive geometry is known.

The SCSI and IDE (ATA) interfaces for the host side of the disk controller offered logical block addressing (block = sector) rather than CHS addressing. The OS no longer had to be aware of the physical geometry of the drive, and the disk controller was able to use the abstraction of logical addressing to implement a more consistent areal density per sector using zone-bit recording.

So the OS should only issue a read or write block operation with a logical block address, and not be too concerned with the drive's geometry.
For example, low-level format is no longer possible through the ATA interface, and the drive's geometry is variable (and unknown to the host) due to zone-bit recording. Bad sector management is typically under sole control of the integrated controller. However you can probably still find some remnants of CHS optimization in various OSes (e.g. drive partitions aligned to a "cylinder").

2. Does the kernel schedule the disk's head movement, or is it the firmware?

It's possible with a seek operation, but more likely the OS uses R/W operations with auto-seek or LBA R/W operations.
However with LBA and modern HDDs that have sizeable cache and zone-bit recording, such seek operations are not needed and can be counterproductive.

Ultimately the disk controller performs the actual seek.

3. Is there a standard spec for the apis exposed by hard disk devices?

ATA/ATAPI is a published specification (although it seems to be in a "working draft" state for 20 years).
See http://www.t13.org/Documents/UploadedDocuments/docs2013/d2161r5-ATAATAPI_Command_Set_-_3.pdf

ABSTRACT This standard specifies the AT Attachment command set used to communicate between host systems and storage devices. This provides a common command set for systems manufacturers, system integrators, software suppliers, and suppliers of storage devices. The AT Attachment command set includes the PACKET feature set implemented by devices commonly known as ATAPI devices. This standard maintains a high degree of compatibility with the ATA/ATAPI Command Set - 2 (ACS-2).