lkml.org 
[lkml]   [2015]   [Apr]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [RFC][PATCH v2 01/13] usb: otg-fsm: Add documentation for struct otg_fsm
On 16/04/15 14:32, Peter Chen wrote:
> On Tue, Apr 14, 2015 at 01:41:48PM +0300, Roger Quadros wrote:
>> struct otg_fsm is the interface to the OTG state machine.
>>
>> Document the input, output and internal state variables.
>> Definations are taken from Table 7-2 and Table 7-4 of
>> the USB OTG & EH Specification Rev.2.0
>>
>> Re-arrange some of the members as per use case for more
>> clarity.
>>
>> Signed-off-by: Roger Quadros <rogerq@ti.com>
>> ---
>> include/linux/usb/otg-fsm.h | 80 +++++++++++++++++++++++++++++++++++++++++----
>> 1 file changed, 73 insertions(+), 7 deletions(-)
>>
>> diff --git a/include/linux/usb/otg-fsm.h b/include/linux/usb/otg-fsm.h
>> index b6ba1bf..c5b74c5 100644
>> --- a/include/linux/usb/otg-fsm.h
>> +++ b/include/linux/usb/otg-fsm.h
>> @@ -57,37 +57,103 @@ enum otg_fsm_timer {
>> NUM_OTG_FSM_TIMERS,
>> };
>>
>> -/* OTG state machine according to the OTG spec */
>> +/**
>> + * struct otg_fsm - OTG state machine according to the OTG spec
>> + *
>> + * OTG hardware Inputs
>> + *
>> + * Common inputs for A and B device
>
> What's the intention you leave two spaces at above line?

It is just to indicate the subgroup. i.e.
1) common inputs
2) a-device inputs
3) b-device inputs, etc

>
>> + * @id: TRUE for B-device, FALSE for A-device.
>> + * @adp_change: TRUE when current ADP measurement (n) value, compared to the
>> + * ADP measurement taken at n-2, differs by more than CADP_THR
>> + * @power_up: TRUE when the OTG device first powers up its USB system and
>> + * ADP measurement taken if ADP capable
>> + *
>> + * A-Device state inputs
>> + * @a_srp_det: TRUE if the A-device detects SRP
>> + * @a_vbus_vld: TRUE when VBUS voltage is in regulation
>> + * @b_conn: TRUE if the A-device detects connection from the B-device
>> + * @a_bus_resume: TRUE when the B-device detects that the A-device is signaling
>> + * a resume (K state)
>> + * B-Device state inputs
>> + * @a_bus_suspend: TRUE when the B-device detects that the A-device has put the bus into suspend
>> + * @a_conn: TRUE if the B-device detects a connection from the A-device
>> + * @b_se0_srp: TRUE when the line has been at SE0 for more than the minimum
>> + * time before generating SRP
>> + * @b_ssend_srp: TRUE when the VBUS has been below VOTG_SESS_VLD for more than
>> + * the minimum time before generating SRP
>> + * @b_sess_vld: TRUE when the B-device detects that the voltage on VBUS is
>> + * above VOTG_SESS_VLD
>> + * @test_device: TRUE when the B-device switches to B-Host and detects an OTG test device
>> + * FIXME: must be set by host/hub driver
>
> Yes, according to pid/vid pair.
>
>> + *
>> + * Application inputs (A-Device)
>> + * @a_bus_drop: TRUE when A-device application needs to power down the bus
>> + * @a_bus_req: TRUE when A-device application wants to use the bus.
>> + * FALSE to suspend the bus
>> + *
>> + * Application inputs (B-Device)
>> + * @b_bus_req: TRUE during the time that the Application running on the
>> + * B-device wants to use the bus
>> + *
>> + * Auxilary inputs
>> + * @a_sess_vld: ??
>
> See OTG spec 1.3, and obsolete now.

OK. I will mark it obsolete.

>
>> + * @b_bus_suspend: ??
>> + * @b_bus_resume: ??
>
> They are used at current otg fsm, just for B-host.

These 2 are also present only in otg v1.3 spec and absent in v2.0 spec.
b_bus_suspend has been replaced by a_bidl_adis_tmout to transition from a_peripheral
to a_wait_bcon.
b_bus_resume has been replaced by a_bus_req to transition between a_suspend and a_host.
So I'll mark them as obsolete as well.

>
>> + *
>> + * OTG Output status. Read only for users. updated by otg_ops() helpers
>> + *
>> + * Outputs for Both A and B device
>> + * @drv_vbus: TRUE when A-device is driving VBUS
>> + * @loc_conn: TRUE when the local device has signaled that it is connected to the bus
>> + * @loc_sof: TRUE when the local device is generating activity on the bus
>> + * @adp_prb: TRUE when the local device is in the process of doing ADP probing
>> + *
>> + * Outputs for B-device state
>> + * @adp_sns: TRUE when the B-device is in the process of carrying out ADP sensing
>> + * @data_pulse: TRUE when the B-device is performing data line pulsing
>> + *
>> + * Internal Variables
>> + *
>> + * a_set_b_hnp_en: TRUE when the A-device has successfully set the b_hnp_enable bit in the B-device.
>> + * FIXME: OTG fsm uses otg->host->b_hnp_enable instead
>
> a_set_b_hnp_en is for otg 2.0 and it should instead of
> otg->host->b_hnp_enable at otg fsm.

both are the same thing. Just that there is no way for HCD drivers to directly access
otg_fsm data structure so we rely on otg->host->b_hnp_enable.

>
>> + * b_srp_done: TRUE when the B-device has completed initiating SRP
>> + * b_hnp_enable: TRUE when the B-device has accepted the SetFeature(b_hnp_enable) B-device
>> + * FIXME: OTG fsm uses otg->gadget->b_hnp_enable instead
>
> Yes
>
>> + * a_clr_err: Asserted (by application ?) to clear a_vbus_err due to an overcurrent condition
>> + * and causes the A-device to transition to a_wait_vfall
>> + */
>> struct otg_fsm {
>> /* Input */
>> int id;
>> int adp_change;
>> int power_up;
>> - int test_device;
>> - int a_bus_drop;
>> - int a_bus_req;
>> int a_srp_det;
>> int a_vbus_vld;
>> int b_conn;
>> int a_bus_resume;
>> int a_bus_suspend;
>> int a_conn;
>> - int b_bus_req;
>> int b_se0_srp;
>> int b_ssend_srp;
>> int b_sess_vld;
>> + int test_device;
>> + int a_bus_drop;
>> + int a_bus_req;
>> + int b_bus_req;
>> +
>> /* Auxilary inputs */
>> int a_sess_vld;
>> int b_bus_resume;
>> int b_bus_suspend;
>>
>> /* Output */
>> - int data_pulse;
>> int drv_vbus;
>> int loc_conn;
>> int loc_sof;
>> int adp_prb;
>> int adp_sns;
>> + int data_pulse;
>>
>> /* Internal variables */
>> int a_set_b_hnp_en;
>> @@ -95,7 +161,7 @@ struct otg_fsm {
>> int b_hnp_enable;
>> int a_clr_err;
>>
>> - /* Informative variables */
>> + /* Informative variables. All unused as of now */
>> int a_bus_drop_inf;
>> int a_bus_req_inf;
>> int a_clr_err_inf;
>> --
>> 2.1.0
>>
>

cheers,
-roger


\
 
 \ /
  Last update: 2015-04-17 11:21    [W:0.302 / U:2.512 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site