Anatomy of a SATA Device Driver - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:23:56Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:23, 26 January 2025
Line 8:		Line 8:

	Creating a resident kickstart module is pretty simple. Here is the resident structure used by the p5020sata.device driver:		Creating a resident kickstart module is pretty simple. Here is the resident structure used by the p5020sata.device driver:
	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	// Priority of resident kernel module		// Priority of resident kernel module
	//		//
Line 35:		Line 35:

	The entry point is named '''launch_dev''' and it looks like this:		The entry point is named '''launch_dev''' and it looks like this:
	<syntaxhighlight>		<syntaxhighlight lang="C" line>

	APTR launch_dev(struct Library lib, APTR seglist, struct ExecBase exec)		APTR launch_dev(struct Library lib, APTR seglist, struct ExecBase exec)
Line 71:		Line 71:

	This is one way to load the kickstart module manually via a shell command:		This is one way to load the kickstart module manually via a shell command:
	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	int main()		int main()
	{		{
Line 133:		Line 133:
	Once inside '''create_sata_device()''' we have to do some trickery to synchronize with '''mounter.library''' and friends. In order to avoid a race condition, we need to create ourselves and add our device manually. Only after that can we inform '''mounter.library''' that we ready to go.		Once inside '''create_sata_device()''' we have to do some trickery to synchronize with '''mounter.library''' and friends. In order to avoid a race condition, we need to create ourselves and add our device manually. Only after that can we inform '''mounter.library''' that we ready to go.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct SataDevice create_sata_device(struct ExecIFace IExec)		struct SataDevice create_sata_device(struct ExecIFace IExec)
	{		{
Line 227:		Line 227:
	What I decided was that Media Toolbox would be the first AmigaOS application I supported. This necessitated knowing what commands Medai Toolbox was sending to my driver so I added some debug code:		What I decided was that Media Toolbox would be the first AmigaOS application I supported. This necessitated knowing what commands Medai Toolbox was sending to my driver so I added some debug code:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	void dev_begin_io(struct DeviceManagerInterface self, struct IOStdReq req)		void dev_begin_io(struct DeviceManagerInterface self, struct IOStdReq req)
	{		{

Steven Solie: /* Why Include SCSI Support? */

2016-10-02T21:57:29Z

Why Include SCSI Support?

← Older revision		Revision as of 21:57, 2 October 2016
Line 315:		Line 315:

	Why? Because libata works a lot better if everything is considered a SCSI command even if it doesn't need to be. Error handling is the key to understanding this complexity. As long as there are no errors, a device driver is pretty simple and it just chugs along happily. Add in errors and you have to decide whether to retry or just give up. Just giving up could be very expensive in terms of time lost. So libata is implemented to handle every device in every scenario and it is the SCSI layer that adds that functionality.		Why? Because libata works a lot better if everything is considered a SCSI command even if it doesn't need to be. Error handling is the key to understanding this complexity. As long as there are no errors, a device driver is pretty simple and it just chugs along happily. Add in errors and you have to decide whether to retry or just give up. Just giving up could be very expensive in terms of time lost. So libata is implemented to handle every device in every scenario and it is the SCSI layer that adds that functionality.

			The reason I avoided SCSI in the first place was to get the driver working for hard drives as quickly as possible. When I added ATAPI support, then SCSI became absolutely necessary.

			= That's It? =

			At this point I suspect we will have likely ran out of time at the Dev Con. There are still dozens of topics to explore and, depending on the room, we can explore a few of them at the Dev Con directly.

			For those reason this article, it will be changed into a full tutorial at some point. Please be patient.

Steven Solie: /* Why Include SCSI Support? */

2016-10-02T21:53:22Z

Why Include SCSI Support?

← Older revision		Revision as of 21:53, 2 October 2016
Line 304:		Line 304:
	# Some program calls the IDOS->Read() function.		# Some program calls the IDOS->Read() function.
	# The Read() function is translated into a port vector call on the underlying file system. In the old days, it would have become a DOS packet.		# The Read() function is translated into a port vector call on the underlying file system. In the old days, it would have become a DOS packet.
	# The file system may or may not divide the read into file system sector-sized chunks and then issues each command to our driver.		# The file system may (NGFS) or may not (FFS2) divide the read into file system sector-sized chunks and then issues each command to our driver.
	# Our driver takes each command and divides it into device sector-sized chunks and issues SCSI commands to the libata framework.		# Our driver takes each command and divides it into device sector-sized chunks and issues SCSI commands to the libata framework.
	# Each SCSI command is translated by libata into an ATA device command.		# Each SCSI command is translated by libata into an ATA device command.

Steven Solie: /* Why Include SCSI Support? */

2016-10-02T21:52:24Z

Why Include SCSI Support?

← Older revision		Revision as of 21:52, 2 October 2016
Line 302:		Line 302:

	Here is a simplified summary of how a read command is executed:		Here is a simplified summary of how a read command is executed:
	1. Some program calls the IDOS->Read() function.		# Some program calls the IDOS->Read() function.
	2. The Read() function is translated into a port vector call on the underlying file system. In the old days, it would have become a DOS packet.		# The Read() function is translated into a port vector call on the underlying file system. In the old days, it would have become a DOS packet.
	3. The file system may or may not divide the read into file system sector-sized chunks and then issues each command to our driver.		# The file system may or may not divide the read into file system sector-sized chunks and then issues each command to our driver.
	4. Our driver takes each command and divides it into device sector-sized chunks and issues SCSI commands to the libata framework.		# Our driver takes each command and divides it into device sector-sized chunks and issues SCSI commands to the libata framework.
	5. Each SCSI command is translated by libata into an ATA device command.		# Each SCSI command is translated by libata into an ATA device command.
	6. The ATA device command is finally sent to the attached device.		# The ATA device command is finally sent to the attached device.
	7. After the command completes it raises an interrupt.		# After the command completes it raises an interrupt.
	8. The interrupt is handled and the various commands are unwound in reverse order.		# The interrupt is handled and the various commands are unwound in reverse order.
	9. Complete commands as required to satisfy the original IDOS->Read() call.		# Complete commands as required to satisfy the original IDOS->Read() call.

	The way the driver is implemented now, the SCSI layer is still not there for read and write requests to hard drives but that is likely to change.		The way the driver is implemented now, the SCSI layer is still not there for read and write requests to hard drives but that is likely to change.

Steven Solie: /* The BeginIO Vector */

2016-10-02T21:51:53Z

The BeginIO Vector

← Older revision		Revision as of 21:51, 2 October 2016
Line 294:		Line 294:
	\| NSCMD_TD_FORMAT64 (0xC003) \|\| Format		\| NSCMD_TD_FORMAT64 (0xC003) \|\| Format
	\|}		\|}

			Over time, each command was implemented one by one using libata to do the actual work of talking to the device.

			= Why Include SCSI Support? =

			For reasons lost to history, SCSI commands are still the preferred way of talking to CD, DVD, etc. devices. At first, I concentrated on hard drives only which meant I could ignore the SCSI support. However, libata is implemented in such a way that '''all''' commands are SCSI commands even if they are for hard drives only.

			Here is a simplified summary of how a read command is executed:
			1. Some program calls the IDOS->Read() function.
			2. The Read() function is translated into a port vector call on the underlying file system. In the old days, it would have become a DOS packet.
			3. The file system may or may not divide the read into file system sector-sized chunks and then issues each command to our driver.
			4. Our driver takes each command and divides it into device sector-sized chunks and issues SCSI commands to the libata framework.
			5. Each SCSI command is translated by libata into an ATA device command.
			6. The ATA device command is finally sent to the attached device.
			7. After the command completes it raises an interrupt.
			8. The interrupt is handled and the various commands are unwound in reverse order.
			9. Complete commands as required to satisfy the original IDOS->Read() call.

			The way the driver is implemented now, the SCSI layer is still not there for read and write requests to hard drives but that is likely to change.

			Why? Because libata works a lot better if everything is considered a SCSI command even if it doesn't need to be. Error handling is the key to understanding this complexity. As long as there are no errors, a device driver is pretty simple and it just chugs along happily. Add in errors and you have to decide whether to retry or just give up. Just giving up could be very expensive in terms of time lost. So libata is implemented to handle every device in every scenario and it is the SCSI layer that adds that functionality.

Steven Solie: /* The BeginIO Vector */

2016-10-02T21:23:06Z

The BeginIO Vector

@@ Line 265: / Line 265: @@
 |-
 | CMD_READ (0x0002) || mounter.library<br/>CrossDOSFileSystem
 |}

Steven Solie: /* The BeginIO Vector */

2016-10-02T21:17:33Z

The BeginIO Vector

← Older revision		Revision as of 21:17, 2 October 2016
Line 262:		Line 262:

	{\|class=wikitable		{\|class=wikitable
			! Command !! Component
			\|-
			\| CMD_READ (0x0002) \|\| mounter.library<br/>CrossDOSFileSystem
	\|}		\|}

Steven Solie: /* The BeginIO Vector */

2016-10-02T21:16:21Z

The BeginIO Vector

← Older revision		Revision as of 21:16, 2 October 2016
Line 225:		Line 225:
	Then you are left with the decision on what to do next. Do you want to read and write data? Do you want to support disk changes? How about disk geometry queries?		Then you are left with the decision on what to do next. Do you want to read and write data? Do you want to support disk changes? How about disk geometry queries?

	What I decided was that Media Toolbox would be the first AmigaOS application I supported. This ~~necessitates~~ knowing what commands Medai Toolbox is sending to my driver so I added some debug code:		What I decided was that Media Toolbox would be the first AmigaOS application I supported. This necessitated knowing what commands Medai Toolbox was sending to my driver so I added some debug code:

	<syntaxhighlight>		<syntaxhighlight>
Line 256:		Line 256:
	...		...
	</syntaxhighlight>		</syntaxhighlight>

			To test, what I do is boot the system via some other method. Then I open a shell and run my test program which loads my driver and opens the Exec device. Then I run Media Toolbox and collect the debug output for analysis.

			Over time, I slowly discovered which components and applications want which commands in order to function. Here is an incomplete table summarizing my discoveries:

			{\|class=wikitable
			\|}

Steven Solie: /* The BeginIO Vector */

2016-10-02T21:13:09Z

The BeginIO Vector

← Older revision		Revision as of 21:13, 2 October 2016
Line 212:		Line 212:
	= The BeginIO Vector =		= The BeginIO Vector =

	Zooming ahead in time we have our devices being recognized and initialized by libata during the AmigaOS device initialization sequence.		Zooming ahead in time we have our devices being recognized and initialized by libata during the AmigaOS device initialization sequence. The '''create_sata_device()''' function is executing which in turn triggers our
			'''dev_init()''' function (via '''IExec->CreateLibrary()''') where the SataPort tasks are launched.

			It wasn't that easy but let's pretend it was.

			Now you have AmigaOS making all sorts of demands on your driver. The demands come in the form of I/O requests which is the way AmigaOS talks to device drivers. They all enter the driver via the '''dev_begin_io()''' function.

			It is possible that any Task in the system is calling your dev_begin_io() function so be careful how it is implemented. There must not be any global data for example. Anything you do need is packaged up in the '''SataDevice'''' structure.

			I started with the NSCMD_DEVICEQUERY command. This is usually the first thing your driver will be asked and it lists all the AmigaOS commands your driver supports. To test it, use your test suite you have been building along with the driver or a tool like Ranger which can query your device at this most basic level.

			Then you are left with the decision on what to do next. Do you want to read and write data? Do you want to support disk changes? How about disk geometry queries?

			What I decided was that Media Toolbox would be the first AmigaOS application I supported. This necessitates knowing what commands Medai Toolbox is sending to my driver so I added some debug code:

			<syntaxhighlight>
			void dev_begin_io(struct DeviceManagerInterface self, struct IOStdReq req)
			{
			struct SataDevice sd = (struct SataDevice)req->io_Device;
			struct SataUnit su = (struct SataUnit)req->io_Unit;

			struct SataPort *sp = su->port; // May be NULL if disk removed.

			struct ExecIFace *IExec = sd->IExec;

			if (sp != NULL)
			{
			IExec->DebugPrintF("%lu:dev_begin_io() unit_num=%lu [%s]\n",
			sp->port_num, su->unit_num, IExec->FindTask(0)->tc_Node.ln_Name);
			IExec->DebugPrintF("%lu:req=%p io_Command=0x%04lx\n",
			sp->port_num, req, req->io_Command);
			}
			else
			{
			IExec->DebugPrintF("?:dev_begin_io() unit_num=%lu [%s]\n",
			su->unit_num, IExec->FindTask(0)->tc_Node.ln_Name);
			IExec->DebugPrintF("?:req=%p io_Command=0x%04lx\n",
			req, req->io_Command);
			}

			switch (req->io_Command)
			{
			...
			</syntaxhighlight>

Steven Solie: /* The BeginIO Vector */

2016-10-02T21:01:18Z

The BeginIO Vector

← Older revision		Revision as of 21:01, 2 October 2016
Line 211:		Line 211:

	= The BeginIO Vector =		= The BeginIO Vector =

			Zooming ahead in time we have our devices being recognized and initialized by libata during the AmigaOS device initialization sequence.