From 597e6db00739dd479ebcf9fe22c3a5ea9465e405 Mon Sep 17 00:00:00 2001 From: eb Date: Thu, 8 Mar 2007 23:07:59 +0000 Subject: [PATCH] beginning of host spec for inband-usb git-svn-id: http://gnuradio.org/svn/gnuradio/trunk@4735 221aa14e-8319-0410-a670-987f0aec2ac5 --- usrp/doc/inband-signaling-usb-host | 258 +++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 usrp/doc/inband-signaling-usb-host diff --git a/usrp/doc/inband-signaling-usb-host b/usrp/doc/inband-signaling-usb-host new file mode 100644 index 00000000..ca306fe6 --- /dev/null +++ b/usrp/doc/inband-signaling-usb-host @@ -0,0 +1,258 @@ +# +# Copyright 2007 Free Software Foundation, Inc. +# +# This file is part of GNU Radio +# +# GNU Radio is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# GNU Radio is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. +# + +This is preliminary design document on the organization of the host +component of the USRP inband signaling implementation over USB. + +Assumptions: we'll have a single usrp_usb_daemon, implemented as an +mblock, that will provide the high-level message based interface to +the USRP. The daemon will handle all resource allocation, muxing and +demuxing for the control and status messages from multiple clients. + +The underlying cross-process IPC mechanism is not yet specified. +All communication will be via messages. + +The external interface to the usrp_usb_daemon will consist of two sets +of replicated ports, one set for the transmit, and one set for +receive. + + +// ------------------------------------------------------------------------ + +// Protocol class usrp_usb_common +// Defined from client's point-of-view +// +// This protocol class is shared by the usrp_usb_tx and usrp_usb_rx +// protocol classes + +// outgoing: + +cmd_allocate_channel(invocation_handle, channel, capacity_reservation) + +invocation_handle +Type Handle +Use The identifier provided by the client to tag the method invocation. + The identifier will be returned with the response, to provide + the client with a mechanism to match asynchronous responses with + commands that generated them. + +channel +Type integer +Use Specifies the Tx channel to allocate + +capacity_reservation +Type float, units are bytes/s +Use Specifies the number of bytes/s of USB capacity to reserve for + this channel. + + +// incoming: + +response_allocate_channel(invocation_handle, status) + +Type Handle +Use The identifier provided by the client in the prompting invocation. + The identifier is returned with the response, so that the + client has a mechanism to match asynchronous responses with + commands that generated them. The value of the invocation_handle + is opaque to the server, and is not required by the server to be unique. + +Type Status +Use Contains the status code for the operation, per FIXME, and + an optional message. + +Preconditions: + a) None + +Postconditions: + a) If successful, the requested channel and USB capacity are + allocated for the client's exclusive use. + + +// outgoing: + +cmd_deallocate_channel(invocation_handle, channel) + +invocation_handle +Type Handle +Use The identifier provided by the client to tag the method invocation. + The identifier will be returned with the response, to provide + the client with a mechanism to match asynchronous responses with + commands that generated them. + +channel +Type integer +Use Specifies the Tx channel to deallocate + + +// incoming: + +response_deallocate_channel(invocation_handle, status) + +Type Handle +Use The identifier provided by the client in the prompting invocation. + The identifier is returned with the response, so that the + client has a mechanism to match asynchronous responses with + commands that generated them. The value of the invocation_handle + is opaque to the server, and is not required by the server to be unique. + +Type Status +Use Contains the status code for the operation, per FIXME, and + an optional message. + +Preconditions: + a) None + +Postconditions: + a) If successful, the requested channel and associated USB capacity + are deallocated, and return to the pool of available resources. + + +// ------------------------------------------------------------------------ + +// Protocol class usrp_usb_tx inherits from usrp_usb_common +// Defined from client's point-of-view + +// outgoing: + +cmd_xmit_raw_frame(invocation_handle, channel, samples, timestamp) + +invocation_handle +Type Handle +Use The identifier provided by the client to tag the method invocation. + The identifier will be returned with the response, to provide + the client with a mechanism to match asynchronous responses with + commands that generated them. + +channel +Type integer +Use Specifies the channel that the frame of samples shall be transmitted on. + +samples +Type homogenous vector of unsigned char +Use These samples must already be in the appropriate format for parsing + by the USRP FPGA. The required format depends on the + configuration associated with this channel. No conversion of + the samples takes place in this method. Samples will be split + into multiple USB data packets as required for transport + across the USB. + +timestamp +Type 32-bit integer +Use Specifies the time at which the first sample in samples + shall be sent to the D/A converter. The format and + interpretation of time is as specified in + inband-signaling-usb. + + +// incoming: + +response_xmit_raw_frame(invocation_handle, status) + +Type Handle +Use The identifier provided by the client in the prompting invocation. + The identifier is returned with the response, so that the + client has a mechanism to match asynchronous responses with + commands that generated them. The value of the invocation_handle + is opaque to the server, and is not required by the server to be unique. + +Type Status +Use Contains the status code for the operation, per FIXME, and + an optional message. + +Preconditions: + a) The specified channel is allocated to this client + +Postconditions: + a) If successful, the samples of the frame have been queued for + transmission to the USRP. + + +// ------------------------------------------------------------------------ + +// Protocol class usrp_usb_rx inherits from usrp_usb_common +// Defined from client's point-of-view + + +// outgoing: + +cmd_recv_raw_samples(invocation_handle, channel) + +invocation_handle +Type Handle +Use The identifier provided by the client to tag the method invocation. + The identifier will be returned with the response, to provide + the client with a mechanism to match asynchronous responses with + commands that generated them. + +channel +Type integer +Use Specifies the channel that the samples shall be received from. + +The client may issue multiple cmd_recv_raw_samples commands to ensure +an uninterrupted flow of samples. The appropriate number of +outstanding cmds to issue is TBD, but is at least 2. + +[Discussion: I'm not sure if this is really the interface we want. +We may want to provide an enable/disable method, and then just begin +streaming samples. Or, we may wan to implement packet boundary +detection in the FPGA, and then return a frame's worth of samples +(potentially in multiple pieces). + +It may be that we need to different modes, one for packet based +reception and one for continuous streaming.] + + +// incoming: + +response_recv_raw_samples(invocation_handle, samples, timestamp, properties) + +Type Handle +Use The identifier provided by the client in the prompting invocation. + The identifier is returned with the response, so that the + client has a mechanism to match asynchronous responses with + commands that generated them. The value of the invocation_handle + is opaque to the server, and is not required by the server to be unique. + +samples +Type homogenous vector of unsigned char +Use Samples as returned by the USRP FPGA. The format of the + returned samples depends on the configuration associated with + this channel. No conversion or unpacking of samples takes place in + this method. + +timestamp +Type 32-bit integer +Use Specifies the time at which the first sample in samples + was received from the A/D converter. The format and + interpretation of time is as specified in + inband-signaling-usb. + +properties +Type Map +Use Returns additional (key, value) pairs associated with the + reception of these samples. In particular, the map may contain + the Received Strength Signal Indication (RSSI) reported by the + front end at the time the first sample was received from the A/D. + +// ------------------------------------------------------------------------ + +To do: control and configuration messages... + -- 2.30.2