SteveJay's Weblog

All | FireWire | General | InfiniBand | PCI Express
« The 1394 Software... | Main | The 1394 Software... »

20050710 Sunday July 10, 2005

The 1394 Software Framework - Outgoing Asynchronous Requests (Part 2 of 2)

OK... here's part 2 of my discussion on the Solaris 1394 Framework's interfaces for sending outgoing asynch requests. This continues my discussion of the Solaris 1394 Software Framework, and in this post I'm going to go over the functions used to allocate, free, and transmit asynch requests (read, write, or lock). In my previous entry, I described the details of the cmd1394_cmd_t structure that is used to encapsulate all the relevant information for an asynch command.




t1394_alloc_cmd()

/*
 * Function:    t1394_alloc_cmd()
 * Input(s):    t1394_hdl               The target "handle" returned by
 *                                          t1394_attach()
 *              flags                   The flags parameter is described below
 *
 * Output(s):   cmdp                    Pointer to the newly allocated command
 *
 * Description: t1394_alloc_cmd() allocates a command for use with the
 *              t1394_read(), t1394_write(), or t1394_lock() interfaces
 *              of the 1394 Software Framework.  By default, t1394_alloc_cmd()
 *              may sleep while allocating memory for the command structure.
 *              If this is undesirable, the target may set the
 *              T1394_ALLOC_CMD_NOSLEEP bit in the flags parameter.  Also,
 *              this call may fail because a target driver has already
 *              allocated MAX_NUMBER_ALLOC_CMDS commands.
 */
int
t1394_alloc_cmd(t1394_handle_t t1394_hdl, uint_t flags, cmd1394_cmd_t **cmdp)

Using this interface, a target driver allocates one command used to issue outgoing asynchronous requests. The Framework limits the total number of commands that a target driver may have outstanding. This limit is fixed and currently defaults to 256 commands.

Context:

Can be called from base kernel context or from interrupt context. If called from interrupt context, flags must be set to T1394_ALLOC_CMD_NOSLEEP.

Parameters:

Return Values:


t1394_free_cmd()

/*
 * Function:    t1394_free_cmd()
 * Input(s):    t1394_hdl               The target "handle" returned by
 *                                          t1394_attach()
 *              flags                   The flags parameter is unused (for now)
 *              cmdp                    Pointer to the command to be freed
 *
 * Output(s):   DDI_SUCCESS             Target successfully freed command
 *              DDI_FAILURE             Target failed to free command
 *
 * Description: t1394_free_cmd() attempts to free a command that has previously
 *              been allocated by the target driver.  It is possible for
 *              t1394_free_cmd() to fail because the command is currently
 *              in-use by the 1394 Software Framework.
 */
/* ARGSUSED */
int
t1394_free_cmd(t1394_handle_t t1394_hdl, uint_t flags, cmd1394_cmd_t **cmdp)

Using this interface, a target driver frees one cmd1394_cmd_t command.

Context:

Can be called from base kernel context or from interrupt context.

Parameters:

Return Values:


t1394_read()

/*
 * Function:    t1394_read()
 * Input(s):    t1394_hdl               The target "handle" returned by
 *                                          t1394_attach()
 *              cmd                     Pointer to the command to send
 *
 * Output(s):   DDI_SUCCESS             Target successful sent the command
 *              DDI_FAILURE             Target failed to send command
 *
 * Description: t1394_read() attempts to send an asynchronous read request
 *              onto the 1394 bus.
 */
int
t1394_read(t1394_handle_t t1394_hdl, cmd1394_cmd_t *cmd)

The t1394_read() command issues an asynchronous read quadlet request of read block request to the indicated address and places the response data into the provided cmd->cmd_u.b.data_block message buffer or cmd->cmd_u.q.quadlet_data

If the CMD1394_OVERRIDE_ADDR option is not set, the 1394 Software Framework fills in the appropriate high-order 16 bits of the cmd_addr field with the 10-bit bus number and 6-bit node ID for the attached device. If the CMD1394_OVERRIDE_ADDR option is set, the Framework uses the complete 64-bit cmd_addr field as provided.

The Framework splits the read request into multiple read requests if any of the following conditions are true.

  1. The specified data length exceeds the prevailing maximum payload size which is either the current maximum payload size or the overridden max_payload value.
  2. The specified data length exceeds the maximum packet size permitted by the current bus speed.

If the CMD1394_DISABLE_ADDR_INCREMENT option is not set, successive read requests are issued with the destination address advancing accordingly. If the CMD1394_DISABLE_ADDR_INCREMENT option is set, the Framework sends each read request to the same destination address.

Context:

Can be called from base kernel context or from interrupt context. If called from interrupt context, cmd_options can not be set to CMD1394_BLOCKING.

Parameters:

Return Values:

If the command succeeds (i.e. if cmd_result equals CMD1394_SUCCESS), the read data is in cmd->cmd_u.b.data_block or cmd->cmd_u.q.quadlet_data and bytes_transferred indicates the total number of bytes read. For block requests, the data block's b_wptr points to the byte following the last read byte.

Possible immediate errors (see 'Error Codes' in my previous blog entry):

Possible completion statuses (in cmd_result) are below. Note that if the operation fails, bytes_transferred indicates if part of the operation succeeded.


t1394_write()

/*
 * Function:    t1394_write()
 * Input(s):    t1394_hdl               The target "handle" returned by
 *                                          t1394_attach()
 *              cmd                     Pointer to the command to send
 *
 * Output(s):   DDI_SUCCESS             Target successful sent the command
 *              DDI_FAILURE             Target failed to send command
 *
 * Description: t1394_write() attempts to send an asynchronous write request
 *              onto the 1394 bus.
 */
int
t1394_write(t1394_handle_t t1394_hdl, cmd1394_cmd_t *cmd)

The t1394_write() command issues an asynchronous write quadlet request of write block request to the indicated address (based on cmd_type) and uses the provided cmd->cmd_u.b.data_block message buffer or cmd->cmd_u.q.quadlet_data field

If the CMD1394_OVERRIDE_ADDR option is not set, the 1394 Software Framework fills in the appropriate high-order 16 bits of the cmd_addr field with the 10-bit bus number and 6-bit node ID for the attached device. If the CMD1394_OVERRIDE_ADDR option is set, the Framework uses the complete 64-bit cmd_addr field as provided.

The Framework splits the write request into multiple write requests if any of the following conditions are true.

  1. The specified data length exceeds the prevailing maximum payload size which is either the current maximum payload size or the overridden max_payload value.
  2. The specified data length exceeds the maximum packet size permitted by the current bus speed.

If the CMD1394_DISABLE_ADDR_INCREMENT option is not set, successive write requests are issued with the destination address advancing accordingly. If the CMD1394_DISABLE_ADDR_INCREMENT option is set, the Framework sends each write request to the same destination address.

Context:

Can be called from base kernel context or from interrupt context. If called from interrupt context, cmd_options can not be set to CMD1394_BLOCKING.

Parameters:

Return Values:

If the command succeeds (i.e. if cmd_result equals CMD1394_SUCCESS), bytes_transferred indicates the total number of bytes written. For block writes, the 1394 Framework transmits the data between the data block's b_rptr and b_wptr and leaves both b_rptr and b_wptr unchanged.

Possible immediate errors (see 'Error Codes' in my previous blog entry):

Possible completion statuses (in cmd_result) are below. Note that if the operation fails, bytes_transferred indicates if part of the operation succeeded.


t1394_lock()

/*
 * Function:    t1394_lock()
 * Input(s):    t1394_hdl               The target "handle" returned by
 *                                          t1394_attach()
 *              cmd                     Pointer to the command to send
 *
 * Output(s):   DDI_SUCCESS             Target successful sent the command
 *              DDI_FAILURE             Target failed to send command
 *
 * Description: t1394_lock() attempts to send an asynchronous lock request
 *              onto the 1394 bus.
 */
int
t1394_lock(t1394_handle_t t1394_hdl, cmd1394_cmd_t *cmd)

There are several lock operations provided by the 1394 Software Framework (above and beyond the basic lock operations provided by IEEE 1394). These are described below (with pseudo-code to describe their operation).

For all lock operations, if the CMD1394_OVERRIDE_ADDR option is not set, the 1394 Software Framework fills in the appropriate high-order 16 bits of the cmd_addr field with the 10-bit bus number and 6-bit node ID for the attached device. If the CMD1394_OVERRIDE_ADDR option is set, the Framework uses the complete 64-bit cmd_addr field as provided.

Context:

Can be called from base kernel context or from interrupt context. If called from interrupt context, cmd_options can not be set to CMD1394_BLOCKING.

Parameters:

Return Values:

Possible immediate errors (see 'Error Codes' in my previous blog entry):

Possible completion statuses (in cmd_result) are below.


(2005-07-10 13:15:00.0) Permalink Comments [1]

Comments:

Great job, Steve. Thanks!

Posted by artem on July 15, 2005 at 12:46 PM EDT #

Post a Comment:

Comments are closed for this entry.