[Hamlib-developer] vfo_t rewrite

[Stephane F. <f8...@fr...>]

Hi everyone,

Here's a rewrite of the vfo_t can of worms (special brand).
The former control band paradigm is gone, mainly because putting too much
capabilities in one data field makes code totaly messed up.

Please comment heavily, the vfo_t rewrite is the only reason holding the
hamlib-1.1.4 release.

I hope the new vfo_t will be saner. It can designate 2 kinds of "VFO"
(ie. control channel): real VFO, and aliases.
- what I call real VFO's are not exactly "Variable Frequency Oscillator",
  but control channels like VFO A, VFO B, VFO C.
- what I call aliases are conceptual channels like "Transmit VFO" and
  "Receive VFO".

Here are the macros that can be used:

aliases:
-------
RIG_VFO_NONE	used in caps, not to be used as a target
RIG_VFO_CURR	the almighty
RIG_VFO_MEM	Memory mode (last selected channel), used by set_vfo, 
		as opposed to VFO mode
RIG_VFO_VFO	VFO mode (last selected VFO), used by set_vfo, 
		as opposed to Memory mode

RIG_VFO_RX	maps to RIG_VFO_CURR
RIG_VFO_TX	maps to the transmit channel associated with RIG_VFO_CURR.
		Therefore, the following 2 calls are equivalent:
			rig_set_split_freq(RIG_VFO_CURR, ..)
			rig_set_freq(RIG_VFO_TX, ..)

RIG_VFO_MAIN	set_vfo switch convenience, not to be used as a target
RIG_VFO_SUB	set_vfo switch convenience, not to be used as a target

"real" VFO's:
------------
RIG_VFO_N(n)	starts from 0, allows at least 20 VFO's for now

RIG_VFO_A 	VFO 0
RIG_VFO_B 	VFO 1
RIG_VFO_C 	VFO 2

Special macro:
RIG_VFO_TX_VFO(v)	Designate the transmit channel of VFO.
			e.g. RIG_VFO_TX_VFO(RIG_VFO_C) is the transmit
			channel associated with VFO C.
			Sometimes, RIG_VFO_TX_VFO(RIG_VFO_C) may
			designate the same VFO as VFO C.

Why the RIG_VFO_TX_VFO? 
----------------------
Because some calls do not have a rig_set_split_xxx to target the
transmit channel, eg. rig_set_ant().


Remarks:
-------
* Some rigs use 2 VFO's to handle the transmit and receive channels.
  However, other models may use only one for both directions (in a half-
  duplex manner). This should be transparent for the application.

* Split combinations are not to be handled here. We need to
  create (or modify) an API call like the following:
  rig_set_plit_vfo(RIG*, vfo_t rx_vfo, split_t split, vfo_t tx_vfo);
  What do you think?

* Call channels should be accessed through a forged memory channel,
  unless they are truly plain VFO. I would recommand to go the memory way
  anyway, because memory channels are saved by application whereas 
  VFO channels aren't (they're kind of temprorary working area).

* For now, only rig.h has been modified. If everyone agrees upon this
  rewrite, all the backend will have to be adaptated to honor this new
  semantic.

* It is already possible to know which VFO has support for which
  frequency band. However, a new field will have to be created 
  in the caps to describe what frequency band is exclusive to which one,
  determining if full-duplex is possible or not.


Here's the relevant part of rig.h:
---------------------------------
/**
 * \brief VFO definition
 *
 * There's several way of using a vfo_t. For most cases, using RIG_VFO_A,
 * RIG_VFO_B, RIG_VFO_CURR, etc., as opaque macros should suffice.
 *
 * Strictly speaking a VFO is Variable Frequency Oscillator.
 * Here, it is referred as a tunable channel, from the radio operator
 * point of view. The channel can be designated individualy by its real 
 * number, or using an alias.
 * Aliases may, or may not be honored by backend, and are defined using
 * high significant bits, like RIG_VFO_MEM, RIG_VFO_MAIN, etc.
 *
 */
typedef int vfo_t;

/** \brief used in caps */
#define RIG_VFO_NONE    0

#define RIG_VFO_TX_FLAG    ((vfo_t)(1<<30))

/** \brief current "tunable channel"/VFO */
#define RIG_VFO_CURR    ((vfo_t)(1<<29))

/** \brief means Memory mode, to be used with set_vfo */
#define RIG_VFO_MEM	((vfo_t)(1<<28))

/** \brief means (last or any)VFO mode, with set_vfo */
#define RIG_VFO_VFO	((vfo_t)(1<<27))

#define RIG_VFO_TX_VFO(v)	((v)|RIG_VFO_TX_FLAG)

/** \brief alias for split tx or uplink, of VFO_CURR  */
#define RIG_VFO_TX	RIG_VFO_TX_VFO(RIG_VFO_CURR)

/** \brief alias for split rx or downlink */
#define RIG_VFO_RX	RIG_VFO_CURR

/** \brief alias for MAIN */
#define RIG_VFO_MAIN	((vfo_t)(1<<26))
/** \brief alias for SUB */
#define RIG_VFO_SUB	((vfo_t)(1<<25))

#define RIG_VFO_N(n) ((vfo_t)(1<<(n)))

/** \brief VFO A */
#define RIG_VFO_A RIG_VFO_N(0)
/** \brief VFO B */
#define RIG_VFO_B RIG_VFO_N(1)
/** \brief VFO C */
#define RIG_VFO_C RIG_VFO_N(2)


If something is not clear, please ask questions. If documentation is too
vague, please complain, or better, propose your own comments!

Application developers, please let me know if this new design does not let
you do what you want.

Backend developers, please let me know if this new design does not let
you describe what your rig can do.


Cheers,
Stephane