aboutsummaryrefslogtreecommitdiffstats
path: root/drivers/scsi/libata-core.c
diff options
context:
space:
mode:
authorEdward Falk <efalk@google.com>2005-06-02 18:17:13 -0400
committerJeff Garzik <jgarzik@pobox.com>2005-06-02 18:17:13 -0400
commit0baab86b00cdf9785ac2bb2ce1ab63995b3866ca (patch)
tree9a92597d6e1653a9a9b3ed7f371d62237e68a6e9 /drivers/scsi/libata-core.c
parent92bab26be5544d8b495389646490fcfdca6dbcf2 (diff)
libata: update inline source docs
Diffstat (limited to 'drivers/scsi/libata-core.c')
-rw-r--r--drivers/scsi/libata-core.c283
1 files changed, 276 insertions, 7 deletions
diff --git a/drivers/scsi/libata-core.c b/drivers/scsi/libata-core.c
index 31b2984f379..86e84ed87be 100644
--- a/drivers/scsi/libata-core.c
+++ b/drivers/scsi/libata-core.c
@@ -186,6 +186,28 @@ static void ata_tf_load_mmio(struct ata_port *ap, struct ata_taskfile *tf)
186 ata_wait_idle(ap); 186 ata_wait_idle(ap);
187} 187}
188 188
189
190/**
191 * ata_tf_load - send taskfile registers to host controller
192 * @ap: Port to which output is sent
193 * @tf: ATA taskfile register set
194 *
195 * Outputs ATA taskfile to standard ATA host controller using MMIO
196 * or PIO as indicated by the ATA_FLAG_MMIO flag.
197 * Writes the control, feature, nsect, lbal, lbam, and lbah registers.
198 * Optionally (ATA_TFLAG_LBA48) writes hob_feature, hob_nsect,
199 * hob_lbal, hob_lbam, and hob_lbah.
200 *
201 * This function waits for idle (!BUSY and !DRQ) after writing
202 * registers. If the control register has a new value, this
203 * function also waits for idle after writing control and before
204 * writing the remaining registers.
205 *
206 * May be used as the tf_load() entry in ata_port_operations.
207 *
208 * LOCKING:
209 * Inherited from caller.
210 */
189void ata_tf_load(struct ata_port *ap, struct ata_taskfile *tf) 211void ata_tf_load(struct ata_port *ap, struct ata_taskfile *tf)
190{ 212{
191 if (ap->flags & ATA_FLAG_MMIO) 213 if (ap->flags & ATA_FLAG_MMIO)
@@ -195,11 +217,11 @@ void ata_tf_load(struct ata_port *ap, struct ata_taskfile *tf)
195} 217}
196 218
197/** 219/**
198 * ata_exec_command - issue ATA command to host controller 220 * ata_exec_command_pio - issue ATA command to host controller
199 * @ap: port to which command is being issued 221 * @ap: port to which command is being issued
200 * @tf: ATA taskfile register set 222 * @tf: ATA taskfile register set
201 * 223 *
202 * Issues PIO/MMIO write to ATA command register, with proper 224 * Issues PIO write to ATA command register, with proper
203 * synchronization with interrupt handler / other threads. 225 * synchronization with interrupt handler / other threads.
204 * 226 *
205 * LOCKING: 227 * LOCKING:
@@ -235,6 +257,18 @@ static void ata_exec_command_mmio(struct ata_port *ap, struct ata_taskfile *tf)
235 ata_pause(ap); 257 ata_pause(ap);
236} 258}
237 259
260
261/**
262 * ata_exec_command - issue ATA command to host controller
263 * @ap: port to which command is being issued
264 * @tf: ATA taskfile register set
265 *
266 * Issues PIO/MMIO write to ATA command register, with proper
267 * synchronization with interrupt handler / other threads.
268 *
269 * LOCKING:
270 * spin_lock_irqsave(host_set lock)
271 */
238void ata_exec_command(struct ata_port *ap, struct ata_taskfile *tf) 272void ata_exec_command(struct ata_port *ap, struct ata_taskfile *tf)
239{ 273{
240 if (ap->flags & ATA_FLAG_MMIO) 274 if (ap->flags & ATA_FLAG_MMIO)
@@ -305,7 +339,7 @@ void ata_tf_to_host_nolock(struct ata_port *ap, struct ata_taskfile *tf)
305} 339}
306 340
307/** 341/**
308 * ata_tf_read - input device's ATA taskfile shadow registers 342 * ata_tf_read_pio - input device's ATA taskfile shadow registers
309 * @ap: Port from which input is read 343 * @ap: Port from which input is read
310 * @tf: ATA taskfile register set for storing input 344 * @tf: ATA taskfile register set for storing input
311 * 345 *
@@ -368,6 +402,23 @@ static void ata_tf_read_mmio(struct ata_port *ap, struct ata_taskfile *tf)
368 } 402 }
369} 403}
370 404
405
406/**
407 * ata_tf_read - input device's ATA taskfile shadow registers
408 * @ap: Port from which input is read
409 * @tf: ATA taskfile register set for storing input
410 *
411 * Reads ATA taskfile registers for currently-selected device
412 * into @tf.
413 *
414 * Reads nsect, lbal, lbam, lbah, and device. If ATA_TFLAG_LBA48
415 * is set, also reads the hob registers.
416 *
417 * May be used as the tf_read() entry in ata_port_operations.
418 *
419 * LOCKING:
420 * Inherited from caller.
421 */
371void ata_tf_read(struct ata_port *ap, struct ata_taskfile *tf) 422void ata_tf_read(struct ata_port *ap, struct ata_taskfile *tf)
372{ 423{
373 if (ap->flags & ATA_FLAG_MMIO) 424 if (ap->flags & ATA_FLAG_MMIO)
@@ -381,7 +432,7 @@ void ata_tf_read(struct ata_port *ap, struct ata_taskfile *tf)
381 * @ap: port where the device is 432 * @ap: port where the device is
382 * 433 *
383 * Reads ATA taskfile status register for currently-selected device 434 * Reads ATA taskfile status register for currently-selected device
384 * and return it's value. This also clears pending interrupts 435 * and return its value. This also clears pending interrupts
385 * from this device 436 * from this device
386 * 437 *
387 * LOCKING: 438 * LOCKING:
@@ -397,7 +448,7 @@ static u8 ata_check_status_pio(struct ata_port *ap)
397 * @ap: port where the device is 448 * @ap: port where the device is
398 * 449 *
399 * Reads ATA taskfile status register for currently-selected device 450 * Reads ATA taskfile status register for currently-selected device
400 * via MMIO and return it's value. This also clears pending interrupts 451 * via MMIO and return its value. This also clears pending interrupts
401 * from this device 452 * from this device
402 * 453 *
403 * LOCKING: 454 * LOCKING:
@@ -408,6 +459,20 @@ static u8 ata_check_status_mmio(struct ata_port *ap)
408 return readb((void __iomem *) ap->ioaddr.status_addr); 459 return readb((void __iomem *) ap->ioaddr.status_addr);
409} 460}
410 461
462
463/**
464 * ata_check_status - Read device status reg & clear interrupt
465 * @ap: port where the device is
466 *
467 * Reads ATA taskfile status register for currently-selected device
468 * and return its value. This also clears pending interrupts
469 * from this device
470 *
471 * May be used as the check_status() entry in ata_port_operations.
472 *
473 * LOCKING:
474 * Inherited from caller.
475 */
411u8 ata_check_status(struct ata_port *ap) 476u8 ata_check_status(struct ata_port *ap)
412{ 477{
413 if (ap->flags & ATA_FLAG_MMIO) 478 if (ap->flags & ATA_FLAG_MMIO)
@@ -415,6 +480,20 @@ u8 ata_check_status(struct ata_port *ap)
415 return ata_check_status_pio(ap); 480 return ata_check_status_pio(ap);
416} 481}
417 482
483
484/**
485 * ata_altstatus - Read device alternate status reg
486 * @ap: port where the device is
487 *
488 * Reads ATA taskfile alternate status register for
489 * currently-selected device and return its value.
490 *
491 * Note: may NOT be used as the check_altstatus() entry in
492 * ata_port_operations.
493 *
494 * LOCKING:
495 * Inherited from caller.
496 */
418u8 ata_altstatus(struct ata_port *ap) 497u8 ata_altstatus(struct ata_port *ap)
419{ 498{
420 if (ap->ops->check_altstatus) 499 if (ap->ops->check_altstatus)
@@ -425,6 +504,20 @@ u8 ata_altstatus(struct ata_port *ap)
425 return inb(ap->ioaddr.altstatus_addr); 504 return inb(ap->ioaddr.altstatus_addr);
426} 505}
427 506
507
508/**
509 * ata_chk_err - Read device error reg
510 * @ap: port where the device is
511 *
512 * Reads ATA taskfile error register for
513 * currently-selected device and return its value.
514 *
515 * Note: may NOT be used as the check_err() entry in
516 * ata_port_operations.
517 *
518 * LOCKING:
519 * Inherited from caller.
520 */
428u8 ata_chk_err(struct ata_port *ap) 521u8 ata_chk_err(struct ata_port *ap)
429{ 522{
430 if (ap->ops->check_err) 523 if (ap->ops->check_err)
@@ -873,10 +966,24 @@ void ata_dev_id_string(u16 *id, unsigned char *s,
873 } 966 }
874} 967}
875 968
969
970/**
971 * ata_noop_dev_select - Select device 0/1 on ATA bus
972 * @ap: ATA channel to manipulate
973 * @device: ATA device (numbered from zero) to select
974 *
975 * This function performs no actual function.
976 *
977 * May be used as the dev_select() entry in ata_port_operations.
978 *
979 * LOCKING:
980 * caller.
981 */
876void ata_noop_dev_select (struct ata_port *ap, unsigned int device) 982void ata_noop_dev_select (struct ata_port *ap, unsigned int device)
877{ 983{
878} 984}
879 985
986
880/** 987/**
881 * ata_std_dev_select - Select device 0/1 on ATA bus 988 * ata_std_dev_select - Select device 0/1 on ATA bus
882 * @ap: ATA channel to manipulate 989 * @ap: ATA channel to manipulate
@@ -884,7 +991,9 @@ void ata_noop_dev_select (struct ata_port *ap, unsigned int device)
884 * 991 *
885 * Use the method defined in the ATA specification to 992 * Use the method defined in the ATA specification to
886 * make either device 0, or device 1, active on the 993 * make either device 0, or device 1, active on the
887 * ATA channel. 994 * ATA channel. Works with both PIO and MMIO.
995 *
996 * May be used as the dev_select() entry in ata_port_operations.
888 * 997 *
889 * LOCKING: 998 * LOCKING:
890 * caller. 999 * caller.
@@ -2127,6 +2236,19 @@ void ata_qc_prep(struct ata_queued_cmd *qc)
2127 * spin_lock_irqsave(host_set lock) 2236 * spin_lock_irqsave(host_set lock)
2128 */ 2237 */
2129 2238
2239
2240
2241/**
2242 * ata_sg_init_one - Prepare a one-entry scatter-gather list.
2243 * @qc: Queued command
2244 * @buf: transfer buffer
2245 * @buflen: length of buf
2246 *
2247 * Builds a single-entry scatter-gather list to initiate a
2248 * transfer utilizing the specified buffer.
2249 *
2250 * LOCKING:
2251 */
2130void ata_sg_init_one(struct ata_queued_cmd *qc, void *buf, unsigned int buflen) 2252void ata_sg_init_one(struct ata_queued_cmd *qc, void *buf, unsigned int buflen)
2131{ 2253{
2132 struct scatterlist *sg; 2254 struct scatterlist *sg;
@@ -2158,6 +2280,18 @@ void ata_sg_init_one(struct ata_queued_cmd *qc, void *buf, unsigned int buflen)
2158 * spin_lock_irqsave(host_set lock) 2280 * spin_lock_irqsave(host_set lock)
2159 */ 2281 */
2160 2282
2283
2284/**
2285 * ata_sg_init - Assign a scatter gather list to a queued command
2286 * @qc: Queued command
2287 * @sg: Scatter-gather list
2288 * @n_elem: length of sg list
2289 *
2290 * Attaches a scatter-gather list to a queued command.
2291 *
2292 * LOCKING:
2293 */
2294
2161void ata_sg_init(struct ata_queued_cmd *qc, struct scatterlist *sg, 2295void ata_sg_init(struct ata_queued_cmd *qc, struct scatterlist *sg,
2162 unsigned int n_elem) 2296 unsigned int n_elem)
2163{ 2297{
@@ -2331,6 +2465,18 @@ static void ata_pio_complete (struct ata_port *ap)
2331 ata_qc_complete(qc, drv_stat); 2465 ata_qc_complete(qc, drv_stat);
2332} 2466}
2333 2467
2468
2469/**
2470 * swap_buf_le16 -
2471 * @buf: Buffer to swap
2472 * @buf_words: Number of 16-bit words in buffer.
2473 *
2474 * Swap halves of 16-bit words if needed to convert from
2475 * little-endian byte order to native cpu byte order, or
2476 * vice-versa.
2477 *
2478 * LOCKING:
2479 */
2334void swap_buf_le16(u16 *buf, unsigned int buf_words) 2480void swap_buf_le16(u16 *buf, unsigned int buf_words)
2335{ 2481{
2336#ifdef __BIG_ENDIAN 2482#ifdef __BIG_ENDIAN
@@ -2992,6 +3138,7 @@ err_out:
2992 return -1; 3138 return -1;
2993} 3139}
2994 3140
3141
2995/** 3142/**
2996 * ata_qc_issue_prot - issue taskfile to device in proto-dependent manner 3143 * ata_qc_issue_prot - issue taskfile to device in proto-dependent manner
2997 * @qc: command to issue to device 3144 * @qc: command to issue to device
@@ -3001,6 +3148,8 @@ err_out:
3001 * classes called "protocols", and issuing each type of protocol 3148 * classes called "protocols", and issuing each type of protocol
3002 * is slightly different. 3149 * is slightly different.
3003 * 3150 *
3151 * May be used as the qc_issue() entry in ata_port_operations.
3152 *
3004 * LOCKING: 3153 * LOCKING:
3005 * spin_lock_irqsave(host_set lock) 3154 * spin_lock_irqsave(host_set lock)
3006 * 3155 *
@@ -3058,7 +3207,7 @@ int ata_qc_issue_prot(struct ata_queued_cmd *qc)
3058} 3207}
3059 3208
3060/** 3209/**
3061 * ata_bmdma_setup - Set up PCI IDE BMDMA transaction 3210 * ata_bmdma_setup_mmio - Set up PCI IDE BMDMA transaction
3062 * @qc: Info associated with this ATA transaction. 3211 * @qc: Info associated with this ATA transaction.
3063 * 3212 *
3064 * LOCKING: 3213 * LOCKING:
@@ -3165,6 +3314,18 @@ static void ata_bmdma_start_pio (struct ata_queued_cmd *qc)
3165 ap->ioaddr.bmdma_addr + ATA_DMA_CMD); 3314 ap->ioaddr.bmdma_addr + ATA_DMA_CMD);
3166} 3315}
3167 3316
3317
3318/**
3319 * ata_bmdma_start - Start a PCI IDE BMDMA transaction
3320 * @qc: Info associated with this ATA transaction.
3321 *
3322 * Writes the ATA_DMA_START flag to the DMA command register.
3323 *
3324 * May be used as the bmdma_start() entry in ata_port_operations.
3325 *
3326 * LOCKING:
3327 * spin_lock_irqsave(host_set lock)
3328 */
3168void ata_bmdma_start(struct ata_queued_cmd *qc) 3329void ata_bmdma_start(struct ata_queued_cmd *qc)
3169{ 3330{
3170 if (qc->ap->flags & ATA_FLAG_MMIO) 3331 if (qc->ap->flags & ATA_FLAG_MMIO)
@@ -3173,6 +3334,20 @@ void ata_bmdma_start(struct ata_queued_cmd *qc)
3173 ata_bmdma_start_pio(qc); 3334 ata_bmdma_start_pio(qc);
3174} 3335}
3175 3336
3337
3338/**
3339 * ata_bmdma_setup - Set up PCI IDE BMDMA transaction
3340 * @qc: Info associated with this ATA transaction.
3341 *
3342 * Writes address of PRD table to device's PRD Table Address
3343 * register, sets the DMA control register, and calls
3344 * ops->exec_command() to start the transfer.
3345 *
3346 * May be used as the bmdma_setup() entry in ata_port_operations.
3347 *
3348 * LOCKING:
3349 * spin_lock_irqsave(host_set lock)
3350 */
3176void ata_bmdma_setup(struct ata_queued_cmd *qc) 3351void ata_bmdma_setup(struct ata_queued_cmd *qc)
3177{ 3352{
3178 if (qc->ap->flags & ATA_FLAG_MMIO) 3353 if (qc->ap->flags & ATA_FLAG_MMIO)
@@ -3181,6 +3356,19 @@ void ata_bmdma_setup(struct ata_queued_cmd *qc)
3181 ata_bmdma_setup_pio(qc); 3356 ata_bmdma_setup_pio(qc);
3182} 3357}
3183 3358
3359
3360/**
3361 * ata_bmdma_irq_clear - Clear PCI IDE BMDMA interrupt.
3362 * @qc: Info associated with this ATA transaction.
3363 *
3364 * Clear interrupt and error flags in DMA status register.
3365 *
3366 * May be used as the irq_clear() entry in ata_port_operations.
3367 *
3368 * LOCKING:
3369 * spin_lock_irqsave(host_set lock)
3370 */
3371
3184void ata_bmdma_irq_clear(struct ata_port *ap) 3372void ata_bmdma_irq_clear(struct ata_port *ap)
3185{ 3373{
3186 if (ap->flags & ATA_FLAG_MMIO) { 3374 if (ap->flags & ATA_FLAG_MMIO) {
@@ -3193,6 +3381,19 @@ void ata_bmdma_irq_clear(struct ata_port *ap)
3193 3381
3194} 3382}
3195 3383
3384
3385/**
3386 * ata_bmdma_status - Read PCI IDE BMDMA status
3387 * @qc: Info associated with this ATA transaction.
3388 *
3389 * Read and return BMDMA status register.
3390 *
3391 * May be used as the bmdma_status() entry in ata_port_operations.
3392 *
3393 * LOCKING:
3394 * spin_lock_irqsave(host_set lock)
3395 */
3396
3196u8 ata_bmdma_status(struct ata_port *ap) 3397u8 ata_bmdma_status(struct ata_port *ap)
3197{ 3398{
3198 u8 host_stat; 3399 u8 host_stat;
@@ -3204,6 +3405,19 @@ u8 ata_bmdma_status(struct ata_port *ap)
3204 return host_stat; 3405 return host_stat;
3205} 3406}
3206 3407
3408
3409/**
3410 * ata_bmdma_stop - Stop PCI IDE BMDMA transfer
3411 * @qc: Info associated with this ATA transaction.
3412 *
3413 * Clears the ATA_DMA_START flag in the dma control register
3414 *
3415 * May be used as the bmdma_stop() entry in ata_port_operations.
3416 *
3417 * LOCKING:
3418 * spin_lock_irqsave(host_set lock)
3419 */
3420
3207void ata_bmdma_stop(struct ata_port *ap) 3421void ata_bmdma_stop(struct ata_port *ap)
3208{ 3422{
3209 if (ap->flags & ATA_FLAG_MMIO) { 3423 if (ap->flags & ATA_FLAG_MMIO) {
@@ -3407,6 +3621,19 @@ err_out:
3407 ata_qc_complete(qc, ATA_ERR); 3621 ata_qc_complete(qc, ATA_ERR);
3408} 3622}
3409 3623
3624
3625/**
3626 * ata_port_start - Set port up for dma.
3627 * @ap: Port to initialize
3628 *
3629 * Called just after data structures for each port are
3630 * initialized. Allocates space for PRD table.
3631 *
3632 * May be used as the port_start() entry in ata_port_operations.
3633 *
3634 * LOCKING:
3635 */
3636
3410int ata_port_start (struct ata_port *ap) 3637int ata_port_start (struct ata_port *ap)
3411{ 3638{
3412 struct device *dev = ap->host_set->dev; 3639 struct device *dev = ap->host_set->dev;
@@ -3420,6 +3647,18 @@ int ata_port_start (struct ata_port *ap)
3420 return 0; 3647 return 0;
3421} 3648}
3422 3649
3650
3651/**
3652 * ata_port_stop - Undo ata_port_start()
3653 * @ap: Port to shut down
3654 *
3655 * Frees the PRD table.
3656 *
3657 * May be used as the port_stop() entry in ata_port_operations.
3658 *
3659 * LOCKING:
3660 */
3661
3423void ata_port_stop (struct ata_port *ap) 3662void ata_port_stop (struct ata_port *ap)
3424{ 3663{
3425 struct device *dev = ap->host_set->dev; 3664 struct device *dev = ap->host_set->dev;
@@ -3720,7 +3959,15 @@ int ata_scsi_release(struct Scsi_Host *host)
3720/** 3959/**
3721 * ata_std_ports - initialize ioaddr with standard port offsets. 3960 * ata_std_ports - initialize ioaddr with standard port offsets.
3722 * @ioaddr: IO address structure to be initialized 3961 * @ioaddr: IO address structure to be initialized
3962 *
3963 * Utility function which initializes data_addr, error_addr,
3964 * feature_addr, nsect_addr, lbal_addr, lbam_addr, lbah_addr,
3965 * device_addr, status_addr, and command_addr to standard offsets
3966 * relative to cmd_addr.
3967 *
3968 * Does not set ctl_addr, altstatus_addr, bmdma_addr, or scr_addr.
3723 */ 3969 */
3970
3724void ata_std_ports(struct ata_ioports *ioaddr) 3971void ata_std_ports(struct ata_ioports *ioaddr)
3725{ 3972{
3726 ioaddr->data_addr = ioaddr->cmd_addr + ATA_REG_DATA; 3973 ioaddr->data_addr = ioaddr->cmd_addr + ATA_REG_DATA;
@@ -3762,6 +4009,20 @@ ata_probe_ent_alloc(struct device *dev, struct ata_port_info *port)
3762 return probe_ent; 4009 return probe_ent;
3763} 4010}
3764 4011
4012
4013
4014/**
4015 * ata_pci_init_native_mode - Initialize native-mode driver
4016 * @pdev: pci device to be initialized
4017 * @port: array[2] of pointers to port info structures.
4018 *
4019 * Utility function which allocates and initializes an
4020 * ata_probe_ent structure for a standard dual-port
4021 * PIO-based IDE controller. The returned ata_probe_ent
4022 * structure can be passed to ata_device_add(). The returned
4023 * ata_probe_ent structure should then be freed with kfree().
4024 */
4025
3765#ifdef CONFIG_PCI 4026#ifdef CONFIG_PCI
3766struct ata_probe_ent * 4027struct ata_probe_ent *
3767ata_pci_init_native_mode(struct pci_dev *pdev, struct ata_port_info **port) 4028ata_pci_init_native_mode(struct pci_dev *pdev, struct ata_port_info **port)
@@ -3843,6 +4104,14 @@ ata_pci_init_legacy_mode(struct pci_dev *pdev, struct ata_port_info **port,
3843 * @port_info: Information from low-level host driver 4104 * @port_info: Information from low-level host driver
3844 * @n_ports: Number of ports attached to host controller 4105 * @n_ports: Number of ports attached to host controller
3845 * 4106 *
4107 * This is a helper function which can be called from a driver's
4108 * xxx_init_one() probe function if the hardware uses traditional
4109 * IDE taskfile registers.
4110 *
4111 * This function calls pci_enable_device(), reserves its register
4112 * regions, sets the dma mask, enables bus master mode, and calls
4113 * ata_device_add()
4114 *
3846 * LOCKING: 4115 * LOCKING:
3847 * Inherited from PCI layer (may sleep). 4116 * Inherited from PCI layer (may sleep).
3848 * 4117 *